Multi Database MCP Server

概述

DB MCP Server 提供了一种标准化方式，让 AI 模型能够同时与多个数据库交互。它基于 FreePeak/cortex 框架构建，使 AI 助手能够通过统一接口，在不同数据库系统中执行 SQL 查询、管理事务、探索架构并分析性能。

核心概念

多数据库支持

与传统数据库连接器不同，DB MCP Server 可以同时连接并与多个数据库交互：

{
  "connections": [
    {
      "id": "mysql1",
      "type": "mysql",
      "host": "localhost",
      "port": 3306,
      "name": "db1",
      "user": "user1",
      "password": "password1"
    },
    {
      "id": "postgres1",
      "type": "postgres",
      "host": "localhost",
      "port": 5432,
      "name": "db2",
      "user": "user2",
      "password": "password2"
    },
    {
      "id": "oracle1",
      "type": "oracle",
      "host": "localhost",
      "port": 1521,
      "service_name": "XEPDB1",
      "user": "user3",
      "password": "password3"
    }
  ]
}

动态生成工具

对于每个已连接的数据库，服务都会自动生成专用工具：

// For a database with ID "mysql1", these tools are generated:
query_mysql1       // Execute SQL queries
execute_mysql1     // Run data modification statements
transaction_mysql1 // Manage transactions
schema_mysql1      // Explore database schema
performance_mysql1 // Analyze query performance

整洁架构

服务遵循整洁架构原则，包含以下层：

1. 领域层：核心业务实体和接口
2. 仓储层：数据访问实现
3. 用例层：应用程序业务逻辑
4. 交付层：外部接口（MCP 工具）

功能

• 同时支持多个数据库：同时连接多个 MySQL、PostgreSQL、SQLite 和 Oracle 数据库
• 延迟加载模式：将连接建立推迟到首次使用时——非常适合包含 10 个以上数据库的配置（通过 --lazy-loading 标志启用）
• 数据库专用工具生成：为每个已连接的数据库自动创建专用工具
• 整洁架构：采用模块化设计，职责划分清晰
• 兼容 OpenAI Agents SDK：完全兼容，可无缝集成 AI 助手
• 动态数据库工具：执行查询、运行语句、管理事务、探索架构、分析性能
• 统一接口：在不同数据库类型之间提供一致的交互模式
• 连接管理：轻松配置多个数据库连接
• 健康检查：启动时自动验证数据库连接状态
• 生产环境保护措施：按数据库强制执行 read_only（通过 query_* 和 execute_* 工具阻止写入），使用 max_rows 截断结果并明确告知，并为每条查询设置超时

生产环境防护措施

保护 Agent 会话，避免查询失控和意外写入：

设置	范围	效果
"read_only": true	每个数据库	通过查询和执行工具同时阻止写入语句（INSERT、UPDATE、DELETE、DDL、修改数据的 CTE、堆叠写入），并在 PostgreSQL/TimescaleDB（default_transaction_read_only=on）和 MySQL（transaction_read_only=1）上由数据库引擎本身强制拒绝；SQLite 以 mode=ro 打开。分类器会移除注释和字符串字面量；遇到无法识别的语句时默认拒绝。
"max_rows": 1000	每个数据库	将结果集截断至 N 行，并附加明确的 [已截断] 提示，让模型知道应优化查询，而不是丢失上下文。0（默认值）表示不限制。
"masking_rules": [...]	每个数据库	在结果离开服务之前，对列名称与规则正则表达式匹配的结果列进行值掩码处理——适用于包括 SELECT * 在内的所有查询形式。策略："fixed_string"（替换为 value）、"null" 和 "partial"（保留末尾 keep_last 个字符可见；更短的值会被完全掩码）。采用第一个匹配的规则；无效模式或未知策略会中止配置加载（失败时关闭）；结果页脚会报告已掩码单元格的数量。按设计，使用别名重命名列会绕过名称匹配。参见 docs/design/column-masking-scoping.md。
"mask_pii": true	每个数据库	根据内容形态而不仅是列名，对查询结果中的 PII 进行脱敏：电子邮件地址、电话号码、信用卡号（经 Luhn 校验）、SSN、IPv4 地址和 19 位以上的标识符，无论出现在哪里，都会替换为 [EMAIL]/[PHONE]/[CREDIT_CARD]/[SSN]/[IP_ADDRESS]/[LONG_NUMBER]——包括规则未覆盖的自由文本列。email/card_number/iban 等列名对应的整列内容都会脱敏。由操作员控制：一旦启用，Agent 无法将其关闭（每次查询的 mask_pii 参数只能额外启用）。可与 masking_rules 组合使用。
"query_timeout": 30	每个数据库	取消超过超时时间（秒）的语句；在存储库层对每种工具（查询、语句、事务、解释、架构检查）强制执行。未设置时默认值为 30s；-1 表示禁用。仅使用环境变量的部署可设置 QUERY_TIMEOUT_SECONDS，为未显式指定超时值的连接填入该值（JSON 优先）。

| DB_MCP_AUDIT_LOG=/path/audit.jsonl | 进程 | 每条已执行语句追加一条 JSONL 记录——包含时间戳、操作（query/execute/tx_*）、数据库、语句（最多 10k 字符）、耗时和错误。包括针对只读数据库的拒绝尝试。尽力写入，失败也不会导致查询失败；文件以 0600 权限创建。 |

纵深防御：只读保护分三层强制执行——应用层分类器、引擎会话默认设置，以及（建议采用的）最小权限数据库用户。Oracle 目前依赖分类器和用户权限。

支持的数据库

数据库	状态	功能
MySQL	✅ 完全支持	查询、事务、架构分析、性能洞察
PostgreSQL	✅ 完全支持（v9.6-17）	查询、事务、架构分析、性能洞察
SQLite	✅ 完全支持	基于文件和内存的数据库，支持 SQLCipher 加密
Oracle	✅ 完全支持（10g-23c）	查询、事务、架构分析、RAC、Cloud Wallet、TNS
TimescaleDB	✅ 完全支持	时间序列查询、超表发现（通过 SQL 设置写入策略）

部署和传输状态

最安全的本地集成方式是 STDIO。HTTP 传输仍在加固中；请勿将当前服务直接暴露到共享网络。

个人／本地 STDIO（推荐）

# Build from the audited source revision
make build

# Use a private, single-connection config
./bin/server -t stdio -c /absolute/path/to/config.local.json

对于 Cursor，请将客户端指向实际的构建输出，并使用绝对路径：

{
  "mcpServers": {
    "local-db": {
      "command": "/absolute/path/to/db-mcp-server/bin/server",
      "args": ["-t", "stdio", "-c", "/absolute/path/to/config.local.json"]
    }
  }
}

对于个人 PostgreSQL／MySQL 连接，请使用只读数据库账户和有界的 query_timeout。对于 SQLite，如果 Agent 只需检查数据，请使用绝对路径的 database_path，并设置 "read_only": true。

旧版 SSE（仅用于兼容）

历史上的 Cortex SSE 传输没有内置身份验证。它默认禁用，且只能在受信任的私有反向代理后显式启用：

./bin/server -t sse -h 127.0.0.1 -p 9092 \
  -allow-insecure-sse -c /absolute/path/to/config.local.json

请勿将此模式用于共享部署。旧版端点不会应用 DB_MCP_API_KEY；请在代理处终止 TLS、进行身份验证并实施网络策略。未来版本将以维护中的 Streamable HTTP 实现替代它。

Streamable HTTP（实验性）

streamable 端点由维护中的 Go MCP SDK 提供支持，支持有状态会话、JSON 或 SSE 响应、通知、GET/DELETE 会话生命周期管理，以及 JSON-RPC 分发。如果未设置 DB_MCP_API_KEY，进程将拒绝启动该端点；在身份验证和一致性测试部署完成之前，请将其置于私有 TLS 网关后。

对于来自浏览器的请求，请设置明确的逗号分隔允许列表：

MCP_ALLOWED_ORIGINS=https://agent.example.com

内置的静态 bearer 密钥是有限范围的试点机制。默认授予 db:read；仅对受信任的写入客户端设置 DB_MCP_API_SCOPES=db:read,db:write。db:admin 仅用于受控管理。对于共享部署，设置 DB_MCP_OIDC_ISSUER 和 DB_MCP_OIDC_AUDIENCE，以使用 OIDC 发现、JWKS 签名验证、发行者／受众检查和主体身份；在制定相关策略之前，仍会有意禁用特定于数据库的作用域。

Docker 开发镜像

已发布的镜像是开发／演示产物，并非企业级加固建议。当前 Dockerfile 以非特权用户身份运行、不包含嵌入式配置，并为兼容本地 Compose 而包含旧版 -allow-insecure-sse 行为。它会公开一个独立的健康检查端口（9093），不适合公开发布。

# Build a local image from this source revision
docker build -t db-mcp-server:local .

# Keep it private; the image's default SSE mode is compatibility-only
docker run --rm -p 127.0.0.1:9092:9092 \
  -p 127.0.0.1:9093:9093 \
  -v "$(pwd)/config.local.json:/app/config.json:ro" \
  db-mcp-server:local

对于团队部署，请等待经过身份验证的 Streamable 传输，并使用非 root、只读文件系统镜像，以及私有网络、外部密钥存储和 TLS/OIDC 网关。

源码安装

# Clone the repository
git clone https://github.com/FreePeak/db-mcp-server.git
cd db-mcp-server

# Build the server
make build

# Run the server
./bin/server -t stdio -c config.json

配置

数据库配置文件

创建一个包含数据库连接的 config.json 文件。schema_version: 1 会启用严格的未知字段验证：

{
  "schema_version": 1,
  "connections": [
    {
      "id": "mysql1",
      "type": "mysql",
      "host": "mysql1",
      "port": 3306,
      "name": "db1",
      "user": "user1",
      "password_env": "DB_MCP_MYSQL_PASSWORD",
      "query_timeout": 60,
      "max_open_conns": 20,
      "max_idle_conns": 5,
      "conn_max_lifetime_seconds": 300,
      "conn_max_idle_time_seconds": 60,
      "read_only": false,
      "max_rows": 1000,
      "masking_rules": [
        { "pattern": "(?i)email", "strategy": "fixed_string", "value": "***MASKED***" },
        { "pattern": "(?i)(ssn|tax_id)", "strategy": "null" }
      ]
    },
    {
      "id": "postgres1",
      "type": "postgres",
      "host": "postgres1",
      "port": 5432,
      "name": "db1",
      "user": "user1",
      "password_env": "DB_MCP_POSTGRES_PASSWORD"
    },
    {
      "id": "sqlite_app",
      "type": "sqlite",
      "database_path": "./data/app.db",
      "journal_mode": "WAL",
      "cache_size": 2000,
      "read_only": false,
      "use_modernc_driver": true,
      "query_timeout": 30,
      "max_open_conns": 1,
      "max_idle_conns": 1
    },
    {
      "id": "sqlite_encrypted",
      "type": "sqlite",
      "database_path": "./data/secure.db",
      "encryption_key": "your-secret-key-here",
      "journal_mode": "WAL",
      "use_modernc_driver": false
    },
    {
      "id": "sqlite_memory",
      "type": "sqlite",
      "database_path": ":memory:",
      "cache_size": 1000,
      "use_modernc_driver": true
    }
  ]
}

密钥引用

请勿直接在 JSON 中填写生产环境凭据。为每个连接使用环境变量名称或挂载的密钥文件：

{
  "id": "prod",
  "type": "postgres",
  "host": "db.internal",
  "port": 5432,
  "name": "app",
  "user": "mcp_reader",
  "password_env": "DB_MCP_PROD_PASSWORD"
}

也支持 password_file 和 encryption_key_env／encryption_key_file。相对文件路径以配置文件所在目录为基准解析；内联值不能与引用同时使用。解析后的值会保留在进程内存中，配置加载器不会打印该值。

命令行选项

# Basic syntax
./bin/server -t <transport> -c <config-file>

# HTTP transport options (legacy SSE requires an explicit opt-in)
./bin/server -t sse -h <hostname> -p <port> -allow-insecure-sse -c <config-file>

# Lazy loading mode (recommended for 10+ databases)
./bin/server -t stdio -c <config-file> --lazy-loading

# Customize log directory (useful for multi-project setups)
./bin/server -t stdio -c <config-file> -log-dir /tmp/db-mcp-logs

# Inline database configuration
./bin/server -t stdio -db-config '{"connections":[...]}'

# Environment variable configuration
export DB_CONFIG='{"connections":[...]}'
./bin/server -t stdio

# Print the build version
./bin/server --version

# Upgrade to the latest published release (verifies SHA-256, swaps the binary)
./bin/server update
./bin/server update -check          # only report whether a newer release exists
./bin/server update -version 1.13.0 # install a specific release

可用标志：

• -t, -transport：传输模式（stdio、旧版 sse 或实验性的 streamable）
• -c, -config：数据库配置文件的路径
• -p, -port：HTTP 端口（默认值：9092）
• -h, -host：HTTP 绑定主机（默认值：127.0.0.1）
• --version：打印构建版本并退出
• -allow-insecure-sse：明确允许在私有开发代理中使用旧版 SSE
• -api-key：实验性 Streamable HTTP 入口的 Bearer 密钥（或使用 DB_MCP_API_KEY）
• -log-level：日志级别（debug、info、warn、error）
• -log-dir：日志文件目录（默认值：当前目录下的 ./logs）
• -db-config：内联 JSON 数据库配置
• -lazy-loading：首次使用时建立连接
• -unified-tools：注册一组带有 database 参数的工具

更新： db-mcp-server update 会解析最新的 GitHub 发行版，根据发行版的 SHA256SUMS 清单验证下载文件，并原地替换正在运行的二进制文件（如果验证失败，则不会改动之前的二进制文件）。它会安装与你的操作系统和架构匹配的资源——之后请重启服务。在 Windows 上，运行中的可执行文件无法替换，因此请通过 npm 安装程序更新。-check 只报告结果，不会下载；-force 会重新安装当前版本。

环境变量

首先加载 .env 文件中的值；实际环境变量优先级更高。JSON 配置文件（CONFIG_PATH/DB_CONFIG_FILE）优先于内联配置和旧版数据库变量。

变量	默认值	用途
CONFIG_PATH / DB_CONFIG_FILE	config.json	多数据库 JSON 配置文件的路径
DB_CONFIG	—	内联 JSON 数据库配置（不存在配置文件时使用）
TRANSPORT_MODE	stdio	未传入 -t 时使用的传输模式
SERVER_PORT	9092	HTTP 端口
MCP_ALLOWED_ORIGINS	空	实验性 Streamable HTTP 允许的浏览器来源，以逗号分隔
DB_MCP_API_KEY	空	实验性 Streamable HTTP 的 Bearer 密钥；请将其保存在密钥管理器中
DB_MCP_API_SCOPES	db:read	必需/授予的权限范围：db:read、db:write 和/或 db:admin
DB_MCP_OIDC_ISSUER	空	OIDC 颁发者 URL；设置后，OIDC/JWT 验证将取代静态试用密钥
DB_MCP_OIDC_AUDIENCE	空	必需的 OIDC 受众/客户端 ID
LOG_LEVEL	info	日志详细程度（debug、info、warn、error）
DISABLE_LOGGING	false	true/1 会完全关闭日志记录
DB_TYPE、DB_HOST、DB_PORT、DB_USER、DB_PASSWORD、DB_NAME	引擎默认值	不存在 JSON 配置时的单数据库回退配置
QUERY_TIMEOUT_SECONDS	未设置	为未设置自身 query_timeout 的连接填充值；负值会禁用上限。JSON 配置优先。
DB_MCP_AUDIT_LOG	未设置	可选的仅追加 JSONL 审计日志路径
VERBOSE	未设置	true/1 会将启动日志级别设为 debug（默认值为 error，即除非设置 LOG_LEVEL，否则不输出日志）
MCP_DISABLE_LOGGING	未设置	丢弃 MCP 协议日志（写入器级开关，独立于 LOG_LEVEL/DISABLE_LOGGING）

SQLite 配置选项

使用 SQLite 数据库时，可以利用以下附加配置选项：

SQLite 连接参数

参数	类型	默认值	描述
database_path	string	必填	SQLite 数据库文件的路径；使用 :memory: 表示内存数据库
encryption_key	string	-	SQLCipher 加密数据库的密钥
read_only	boolean	false	以只读模式打开数据库
max_rows	integer	unlimited	每次查询返回的最大行数；超出部分会被截断，并明确告知。适用于所有数据库类型
cache_size	integer	2000	SQLite 缓存页数
journal_mode	string	"WAL"	日志模式：DELETE、TRUNCATE、PERSIST、WAL、OFF
use_modernc_driver	boolean	true	使用 modernc.org/sqlite（无需 CGO）或 mattn/go-sqlite3

SQLite 示例

基本文件数据库

{
  "id": "my_sqlite_db",
  "type": "sqlite",
  "database_path": "./data/myapp.db",
  "journal_mode": "WAL",
  "cache_size": 2000
}

加密数据库（SQLCipher）

{
  "id": "encrypted_db",
  "type": "sqlite",
  "database_path": "./data/secure.db",
  "encryption_key": "your-secret-encryption-key",
  "use_modernc_driver": false
}

内存数据库

{
  "id": "memory_db",
  "type": "sqlite",
  "database_path": ":memory:",
  "cache_size": 1000
}

只读数据库

{
  "id": "reference_data",
  "type": "sqlite",
  "database_path": "./data/reference.db",
  "read_only": true,
  "journal_mode": "DELETE"
}

Oracle 配置选项

使用 Oracle 数据库时，可利用以下其他配置选项：

Oracle 连接参数

参数	类型	默认值	描述
host	string	必填	Oracle 数据库主机
port	integer	1521	Oracle 监听器端口
service_name	string	-	服务名称（RAC 推荐使用）
sid	string	-	系统标识符（旧版方式，请改用 service_name）
user	string	必填	数据库用户名
password	string	必填	数据库密码
wallet_location	string	-	Oracle Cloud wallet 目录的路径
tns_admin	string	-	包含 tnsnames.ora 的目录路径
tns_entry	string	-	tnsnames.ora 中的命名条目
edition	string	-	基于版本的重定义版本名称
pooling	boolean	false	启用驱动程序级连接池
standby_sessions	boolean	false	允许在备用数据库上执行查询
nls_lang	string	AMERICAN_AMERICA.AL32UTF8	字符集配置

Oracle 示例

基本 Oracle 连接（开发）

{
  "id": "oracle_dev",
  "type": "oracle",
  "host": "localhost",
  "port": 1521,
  "service_name": "XEPDB1",
  "user": "testuser",
  "password": "testpass",
  "max_open_conns": 50,
  "max_idle_conns": 10,
  "conn_max_lifetime_seconds": 1800
}

使用 SID 连接 Oracle（旧版方式）

{
  "id": "oracle_legacy",
  "type": "oracle",
  "host": "oracledb.company.com",
  "port": 1521,
  "sid": "ORCL",
  "user": "app_user",
  "password": "app_password"
}

Oracle Cloud Autonomous Database（使用 Wallet）

{
  "id": "oracle_cloud",
  "type": "oracle",
  "user": "ADMIN",
  "password": "your-cloud-password",
  "wallet_location": "/path/to/wallet_DBNAME",
  "service_name": "dbname_high"
}

Oracle RAC（真正应用集群）

{
  "id": "oracle_rac",
  "type": "oracle",
  "host": "scan.company.com",
  "port": 1521,
  "service_name": "production",
  "user": "app_user",
  "password": "app_password",
  "max_open_conns": 100,
  "max_idle_conns": 20
}

使用 TNS 条目连接 Oracle

{
  "id": "oracle_tns",
  "type": "oracle",
  "tns_admin": "/opt/oracle/network/admin",
  "tns_entry": "PROD_DB",
  "user": "app_user",
  "password": "app_password"
}

使用基于版本的重定义连接 Oracle

{
  "id": "oracle_ebr",
  "type": "oracle",
  "host": "oracledb.company.com",
  "port": 1521,
  "service_name": "production",
  "user": "app_user",
  "password": "app_password",
  "edition": "v2_0"
}

Oracle 连接字符串优先级

配置了多种连接方式时，将按以下优先级使用：

1. TNS 条目（配置了 tns_entry 和 tns_admin 时）
2. Wallet（配置了 wallet_location 时）——用于 Oracle Cloud
3. 标准方式（host:port/service_name）——默认方式

可用工具

对于每个已连接的数据库，DB MCP Server 会自动生成以下专用工具：

查询工具

工具名称	描述
query_<db_id>	执行 SELECT 查询并以表格数据集形式返回结果。可选的 mask_pii 布尔值会根据内容特征对 PII 进行脱敏（参见防护措施表）；此选项是附加的——配置为 "mask_pii": true 的数据库始终会进行脱敏。
execute_<db_id>	运行数据操作语句（INSERT、UPDATE、DELETE）。可选的 dry_run 布尔值会离线对语句进行分类——类型、风险级别、提示——但不会执行任何操作；实际运行的破坏性语句会在结果中附带 ⚠ Risk notice。
transaction_<db_id>	开始、提交和回滚事务。还提供撤销操作：list_snapshots 和 rollback_snapshot（使用 snapshot_id）。通过 execute_<db_id> 运行的每个 DELETE/UPDATE 都会记录受影响行的变更前快照——尽力执行，每个数据库最多保留最近 25 个——并在结果中报告其 ID。

架构工具

工具名称	说明
schema_<db_id>	获取有关表、列、索引和外键的信息
generate_schema_<db_id>	根据数据库架构生成 SQL 或代码

性能工具

工具名称	说明
performance_<db_id>	通过以下操作分析查询性能：stats / slow_queries（进程内跟踪器）、engine_slow_queries（pg_stat_statements / MySQL digest 表 / Oracle v$sqlarea）、suggest（静态 SQL 检查）、suggest_indexes（针对单条语句提供基于启发式的 CREATE INDEX 建议，复合索引优先使用等值条件，并通过 EXPLAIN 验证）、validate_suggestions（PostgreSQL：通过 hypopg 扩展将相同的建议安装为零成本假设索引，并报告规划器是否实际选择了每个索引——以真实验证取代手动 EXPLAIN）、workload_suggestions（对执行次数加权，针对成本最高的前 N 条工作负载语句进行相同分析）、index_health（从系统目录中查找重复/冗余/未使用/无效索引和表膨胀；在引擎统计数据可用时提供使用证据）、db_health（包含 index_health 的所有检查，并提供连接压力使用率与 max_connections 的对比）、reset
explain_<db_id>	显示 SQL 语句的执行计划，但不运行该语句；analyze: true 会执行语句并提供计时/缓冲区统计信息（PostgreSQL/MySQL）。只读数据库会阻止写入操作
describe_<db_id>	通过引擎系统目录查询，检查一个表的列、索引和行数估计值
health_<db_id>	报告连接状态、 ping 延迟、连接池状态和引擎统计信息（PostgreSQL 缓冲区缓存命中率、MySQL InnoDB 缓冲区效率）

TimescaleDB 工具

对于安装了 timescaledb 扩展的 PostgreSQL 数据库，启动时会自动注册以下专用工具（注册由配置驱动，因此在 --lazy-loading 模式下也适用；每个处理程序都会在调用时检查扩展是否存在，若不存在则返回可采取行动的错误信息）：

工具名称	说明
timescaledb_timeseries_query_<db_id>	执行经过优化的时间序列查询，支持时间分桶（time_bucket）、筛选和窗口函数
timescaledb_analyze_timeseries_<db_id>	分析一个表/列的时间序列模式（趋势、季节性摘要）
timescaledb_list_hypertables_<db_id>	列出超表及其时间列和维度数量（只读）
timescaledb_compression_settings_<db_id>	显示超表的压缩配置（只读）
timescaledb_retention_policy_<db_id>	显示已配置的保留策略（只读）
timescaledb_list_continuous_aggregates_<db_id>	列出连续聚合及其分桶间隔和刷新策略（只读）
timescaledb_continuous_aggregate_info_<db_id>	详细检查一个连续聚合（只读）

在统一模式下，相同的七个工具各出现一次，名称分别为 timescaledb_timeseries_query、 timescaledb_analyze_timeseries、timescaledb_list_hypertables、 timescaledb_compression_settings、timescaledb_retention_policy、 timescaledb_list_continuous_aggregates 和 timescaledb_continuous_aggregate_info， 每个工具都需要一个 database 参数。

范围说明：上述只读发现操作通过查询管道执行，因此在 read_only 数据库上仍可使用；每个处理程序都会先检查 timescaledb 扩展。写入策略操作（创建超表、切换压缩、添加/移除保留或刷新策略）仍未开放——目前请通过查询/执行工具使用普通 SQL。如需详细文档，请参阅 TIMESCALEDB_TOOLS.md。

统一工具模式

如果连接了许多数据库（5 个以上），按数据库分别命名工具会产生大量工具（5 × N）。一些 MCP 客户端——尤其是 Claude——会严格限制工具总数和工具描述的大小，导致 Agent 无法加载服务、忽略工具或拒绝调用工具。Issue #18 记录了这一具体问题：“db-mcp-server 无法在 Claude 中正常运行，尽管它在 OpenAI 中运行良好”。

对于这些客户端，启动服务时使用 --unified-tools 标志，注册六个整合后的工具（query、execute、transaction、performance、explain、describe、schema、filter_tables），而不是按数据库分别注册工具：

./bin/server -t stdio -c config.json --unified-tools

上下文窗口开销（实测，TestToolTokenBenchmark，2026-08 通过 scripts/token-benchmark.sh 重新验证）： 统一模式的开销约为 1.25–1.6k 个令牌，与连接的数据库数量无关；而按数据库分别注册工具的模式，每个数据库约需 800 个令牌（每个数据库 7 个工具）——连接 10 个数据库约需 8k 个令牌，使用统一模式可节省 80% 的线上传输负载。只连接一个数据库时，按数据库分别命名略省；从两个数据库起，统一模式更省，且之后开销保持不变。你可以使用 scripts/token-benchmark.sh 自行重新测量实际线上传输负载；方法和结果见 docs/benchmark-token-efficiency.md。

In unified mode, each tool accepts a required `database` parameter that names
which database the call should target. See the [Configuration](#configuration)
section for the full list of available databases. This dramatically reduces the
tool count and the cumulative description size, which resolves the Claude
compatibility issues.

For very large configurations, also enable `--lazy-loading` so that startup
doesn't open connections to databases that may never be queried during the
session.

## Examples

### Querying Multiple Databases

```sql
-- Query the MySQL database
query_mysql1("SELECT * FROM users LIMIT 10")

-- Query the PostgreSQL database in the same context
query_postgres1("SELECT * FROM products WHERE price > 100")

-- Query the SQLite database
query_sqlite_app("SELECT * FROM local_data WHERE created_at > datetime('now', '-1 day')")

-- Query the Oracle database
query_oracle_dev("SELECT * FROM employees WHERE hire_date > SYSDATE - 30")

管理事务

transaction_<db_id> 工具支持 begin、execute、commit 和 rollback 操作。每次 begin 都会返回一个 transactionId；将其传回以暂存语句，并提交或回滚：

// 1. Start a transaction
{ "action": "begin" }
// → { "transactionId": "tx_mysql1_1730000000000000000" }

// 2. Execute statements within the transaction
{
  "action": "execute",
  "transactionId": "tx_mysql1_1730000000000000000",
  "statement": "INSERT INTO orders (customer_id, product_id) VALUES (1, 2)"
}

// 3a. Commit — persists all staged statements
{ "action": "commit", "transactionId": "tx_mysql1_1730000000000000000" }

// 3b. OR rollback — discards all staged statements
{ "action": "rollback", "transactionId": "tx_mysql1_1730000000000000000" }

未知或已失效的事务 ID 会返回明确错误，而不是静默成功，因此 Agent 可以检测并恢复丢失事务的情况。

探索数据库架构

-- Get all tables in the database
schema_mysql1("tables")

-- Get columns for a specific table
schema_mysql1("columns", "users")

-- Get constraints
schema_mysql1("constraints", "orders")

使用 SQLite 特有功能

-- Create a table in SQLite
execute_sqlite_app("CREATE TABLE IF NOT EXISTS local_cache (key TEXT PRIMARY KEY, value TEXT, timestamp DATETIME)")

-- Use SQLite-specific date functions
query_sqlite_app("SELECT * FROM events WHERE date(created_at) = date('now')")

-- Query SQLite master table for schema information
query_sqlite_app("SELECT name, sql FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")

-- Performance optimization with WAL mode
execute_sqlite_app("PRAGMA journal_mode = WAL")
execute_sqlite_app("PRAGMA synchronous = NORMAL")

使用 Oracle 特有功能

-- Query user tables (excludes system schemas)
query_oracle_dev("SELECT table_name FROM user_tables ORDER BY table_name")

-- Use Oracle-specific date functions
query_oracle_dev("SELECT employee_id, hire_date FROM employees WHERE hire_date >= TRUNC(SYSDATE, 'YEAR')")

-- Oracle sequence operations
execute_oracle_dev("CREATE SEQUENCE emp_seq START WITH 1000 INCREMENT BY 1")
query_oracle_dev("SELECT emp_seq.NEXTVAL FROM DUAL")

-- Oracle-specific data types
query_oracle_dev("SELECT order_id, TO_CHAR(order_date, 'YYYY-MM-DD HH24:MI:SS') FROM orders")

-- Get schema metadata from Oracle data dictionary
query_oracle_dev("SELECT column_name, data_type, nullable FROM user_tab_columns WHERE table_name = 'EMPLOYEES'")

-- Use Oracle analytic functions
query_oracle_dev("SELECT employee_id, salary, RANK() OVER (ORDER BY salary DESC) as salary_rank FROM employees")

故障排除

常见问题

• 连接失败：验证网络连接和数据库凭据
• 权限错误：确保数据库用户拥有适当的权限
• 超时问题：检查配置中的 query_timeout 设置

日志

启用详细日志记录以进行故障排除：

./bin/server -t sse -c config.json -v

测试

运行测试

项目包含针对所有受支持数据库的全面单元测试和集成测试。

单元测试

运行单元测试（无需数据库）：

make test
# or
go test -short ./...

集成测试

集成测试需要正在运行的数据库实例。我们提供了 Docker Compose 配置，方便快速设置。

测试所有数据库：

# Start test databases
docker-compose -f docker-compose.test.yml up -d

# Run all integration tests
go test ./... -v

# Stop test databases
docker-compose -f docker-compose.test.yml down -v

测试 Oracle Database：

# Start Oracle test environment
./oracle-test.sh start

# Run Oracle tests
./oracle-test.sh test
# or manually
ORACLE_TEST_HOST=localhost go test -v ./pkg/db -run TestOracle
ORACLE_TEST_HOST=localhost go test -v ./pkg/dbtools -run TestOracle

# Stop Oracle test environment
./oracle-test.sh stop

# Full cleanup (removes volumes)
./oracle-test.sh cleanup

测试 TimescaleDB：

# Start TimescaleDB test environment
./timescaledb-test.sh start

# Run TimescaleDB tests
TIMESCALEDB_TEST_HOST=localhost go test -v ./pkg/db/timescale ./internal/delivery/mcp

# Stop TimescaleDB test environment
./timescaledb-test.sh stop

回归测试

针对所有数据库类型运行全面回归测试：

# Ensure all test databases are running
docker-compose -f docker-compose.test.yml up -d
./oracle-test.sh start

# Run regression tests
MYSQL_TEST_HOST=localhost \
POSTGRES_TEST_HOST=localhost \
ORACLE_TEST_HOST=localhost \
go test -v ./pkg/db -run TestRegression

# Run connection pooling tests
go test -v ./pkg/db -run TestConnectionPooling

持续集成

所有测试都会通过 GitHub Actions 在每个拉取请求中自动运行。CI 流水线包括：

• 单元测试：无需数据库连接的快速测试
• 集成测试：针对 MySQL、PostgreSQL、SQLite 和 Oracle 数据库的测试
• 回归测试：确保向后兼容性的全面测试
• Lint 检查：使用 golangci-lint 进行代码质量检查

贡献

欢迎为 DB MCP Server 项目贡献！请按以下步骤操作：

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'feat: add amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 创建 Pull Request

详细指南请参阅 CONTRIBUTING.md。

测试你的更改

提交拉取请求前，请确保：

1. 所有单元测试均通过：go test -short ./...
2. 受影响数据库的集成测试均通过
3. 代码符合项目的风格指南：golangci-lint run ./...
4. 新功能包含适当的测试覆盖

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。