MCP Database

英语| 简体中文

MCP数据库服务

一个用于模型上下文协议（MCP）的多数据库MCP服务器，用TypeScript编写。

它支持MySQL、PostgreSQL、Oracle、openGauss和Redis，具有懒惰的短期连接、面向读取的数据库工具、SQL计划分析、配置重新加载和有保护的写执行。

该项目适用于需要安全数据库发现、查询、性能分析和受控写入操作的AI代理和MCP客户端。

快速开始

从npm安装：

npm install -g @jadchene/mcp-database-service
mcp-database-service --config ./config/databases.example.json

从源代码运行：

npm install
npm run build
node dist/index.js --config ./config/databases.example.json

技能整合（推荐）

对于AI助手（Codex/Gemini/类似代理），该存储库包括一个数据库MCP技能，可以提高工作流程的一致性和写入安全性。

• 技能路径： skills/database-mcp/SKILL.md
• 优点：

- 标准化的数据库发现和模式检查流程 - 查询优先默认值，具有更安全的结果大小和列选择行为 - 明确写操作的两步确认规则

当您的代理支持技能时，请在使用数据库MCP工具之前加载此技能以获得最佳结果。

支持矩阵

笔记：

• show_create_table目前支持MySQL和Oracle。PostgreSQL和openGauss目前返回NOT_SUPPORTED。
• 操作工具，如 show_variables, find_long_running_queries, find_blocking_sessions，以及 show_locks 取决于配置的数据库帐户的可见性和权限。

支持的数据库

• MySQL
• 甲骨文
• PostgreSQL
• openGauss（通过PostgreSQL协议兼容性）
• 瑞迪斯

特性

• 单个配置文件中有多个命名数据库目标
• 可选的文件日志记录，带有可配置的输出目录
• 手动重新加载配置，无需重新启动MCP服务器
• 当磁盘上的JSON文件发生变化时自动重新加载配置
• 查询工具的严格只读强制
• 可选的写入执行，对可写目标进行显式MCP确认
• 延迟连接，每次请求后都有保证的清理
• SQL数据库的元数据发现工具
• Redis专用读取工具

配置

通过以下方法之一提供配置路径：

1. node dist/index.js --config ./config/databases.json
2. 集 MCP_DATABASE_CONFIG=/absolute/path/to/databases.json

配置文件必须是具有所需顶级的JSON对象 databases 阵列。可选的顶级部分，如 logging 和 query 也可以提供。例子：

{
  "logging": {
    "enabled": true,
    "directory": "./logs"
  },
  "query": {
    "timeoutMs": 5000
  },
  "databases": [
    {
      "key": "main-mysql",
      "type": "mysql",
      "readonly": true,
      "connection": {
        "host": "127.0.0.1",
        "port": 3306,
        "databaseName": "app_db",
        "user": "root",
        "password": "secret",
        "connectTimeoutMs": 5000
      }
    }
  ]
}

logging.enabled 默认为 false。启用后，默认情况下日志会写入系统临时目录。你可以用以下命令覆盖它 logging.directory，并且相对于配置文件位置解析相对路径。在上面的示例中，日志被写入 ./logs.

query.timeoutMs 是可选的。设置后，服务器会对数据库操作应用查询超时。在上面的示例中，查询在以下时间后超时 5000 毫秒。

Oracle支持瘦模式和厚模式。厚模式使用相同的 oracledb 包，但需要主机上的Oracle Instant Client。例子：

{
  "key": "oracle-thick-example",
  "type": "oracle",
  "readonly": true,
  "connection": {
    "host": "127.0.0.1",
    "port": 1521,
    "serviceName": "XEPDB1",
    "user": "system",
    "password": "secret",
    "clientMode": "thick",
    "clientLibDir": "C:\\oracle\\instantclient_19_25"
  }
}

可用的MCP工具

• show_loaded_config：显示当前内存中的配置路径、加载时间和所有配置的数据库目标
• reload_config：重新加载当前正在使用的JSON配置文件，并在成功时自动替换内存中的配置
• list_databases：列出所有配置的目标键和逻辑数据库名称，而不打开数据库连接
• ping_database：测试一个配置目标的连接
• list_schemas：列出一个SQL目标的架构
• list_tables：列出一个SQL架构或默认架构下的表/视图
• list_views：在一个SQL架构或默认架构下列出视图
• describe_table：在编写联接、报表或优化SQL之前检查列
• show_create_table：检查当前数据库支持的确切数据库端DDL
• search_tables：按部分名称搜索表或视图
• search_columns：在架构中按部分名称搜索列
• list_indexes：检查表索引以进行性能分析
• get_table_statistics：检查近似行数、存储度量和特定于数据库的表统计信息
• show_variables：检查数据库运行时配置变量
• find_long_running_queries：检查当前运行的会话是否超过持续时间阈值
• find_blocking_sessions：检查会话之间的当前阻塞关系
• show_locks：检查数据库公开的当前锁行
• execute_query：运行一个只读SQL查询；传递原始查询SQL，而不是编写SQL
• explain_query：获取一个只读SQL查询的静态执行计划；传递原始查询SQL，而不是 EXPLAIN ...
• analyze_query：获取一个只读SQL查询的运行时分析；传递原始查询SQL，而不是 EXPLAIN ANALYZE ...
• execute_statement：在明确手动确认后，在可写目标上运行一个非查询SQL语句
• redis_get：读取一个Redis字符串键
• redis_hgetall：读取一个Redis哈希键
• redis_scan：游标使用可选模式安全扫描Redis键

发展

npm install
npm run build
node dist/index.js --config ./config/databases.example.json

全球安装

此项目公开了一个名为的CLI命令 mcp-database-service 通过包裹 bin 现场。

推荐选项：

1. 从npm安装：

npm install -g @jadchene/mcp-database-service

1. 或者使用辅助脚本从本地源代码树安装：

pwsh -File .\scripts\install-global.ps1

或者在Linux/macOS上：

sh ./scripts/install-global.sh

辅助脚本安装依赖项，构建项目，创建tarball npm pack，使用以下命令全局安装tarball npm install -g ，然后删除临时tarball。他们不使用 npm link.

1. 或者手动安装包装好的皮球：

npm pack
npm install -g .\jadchene-mcp-database-service-0.1.5.tgz

该包仅通过以下方式发布运行时文件 files 现场，因此打包安装包括 dist 以及运行时的README/config示例，而不是整个源代码树。

安装后，可以这样使用该命令：

mcp-database-service --config .\config\databases.example.json

MCP服务器配置示例：

{
  "mcpServers": {
    "database": {
      "command": "mcp-database-service",
      "args": [
        "--config",
        "C:\\path\\to\\databases.json"
      ]
    }
  }
}

MCP客户端配置

以下示例显示了如何在常见的AI客户端中注册此MCP服务器。将配置路径替换为您自己的本地文件路径。为了保持设置的便携性，下面的示例有意避免使用绝对路径。

法典

~/.codex/config.toml

[mcp_servers.database]
command = "mcp-database-service"
args = ["--config", "./config/databases.json"]

双子星命令行工具

~/.gemini/settings.json

{
  "mcpServers": {
    "database": {
      "type": "stdio",
      "command": "mcp-database-service",
      "args": [
        "--config",
        "./config/databases.json"
      ]
    }
  }
}

克劳德代码

~/.claude.json

{
  "mcpServers": {
    "database": {
      "type": "stdio",
      "command": "mcp-database-service",
      "args": [
        "--config",
        "./config/databases.json"
      ]
    }
  }
}

配置重新加载

• 服务器在启动时加载JSON配置文件，并保存一个经过验证的内存快照。
• 服务器还会监视相同的JSON文件，并在检测到磁盘上的更改后自动重新加载它。
• 取消了自动重新加载，以避免过于激进地重新加载半写文件。
• 您仍然可以使用 reload_config 强制手动重新加载而不重新启动进程。
• 重新加载是原子性的：如果新文件无效，旧的内存配置将保持活动状态。
• show_loaded_config 可用于检查当前配置路径、加载时间和配置的数据库目标。
• show_loaded_config 还包括当前日志记录状态、解析的日志目录和配置的查询超时。
• show_loaded_config 还包括每个目标的净化连接摘要，如主机、端口、数据库名或服务名、用户名和Oracle客户端模式，但它从不公开密码。

Oracle笔记

• 当满足以下条件时，默认模式为精简模式 clientMode 省略。
• 厚模式需要 clientMode: "thick" 以及一个有效的 clientLibDir.
• 一个进程中的所有Oracle目标必须使用相同的客户端模式。厚模式目标也必须共享相同的 clientLibDir.
• analyze_query Oracle目前不支持，将返回 NOT_SUPPORTED.

撰写陈述

• execute_query 保持只读并阻止非查询SQL。
• execute_statement 仅适用于可写SQL目标。
• execute_statement 需要 readonly: false 在目标数据库配置上。
• 在执行非查询SQL语句之前，当客户端支持时，服务器会通过MCP启发向MCP客户端请求明确的用户确认。
• 如果MCP客户端不支持启发， execute_statement 自动退回到两步确认流程：第一次呼叫返回确认详细信息和 confirmationId，第二次调用必须重新发送相同的SQL confirmationId 和 confirmExecution: true 在用户确认之后。
• execute_statement 确认包括SQL类型、目标对象、SQL预览、参数预览和危险语句的风险提示。