dbmcp

Database MCP

一款用于 SQL 数据库的单二进制文件 MCP 服务。无需任何运行时依赖，即可将 AI 助手连接到 MySQL/MariaDB、PostgreSQL 或 SQLite。

网站 · 文档 · 发布版本

功能 ✨

• 多数据库 — 一个二进制文件即可支持 MySQL/MariaDB、PostgreSQL 和 SQLite
• MCP 工具 — 架构发现（listDatabases、listTables、listViews、listTriggers、listFunctions、listProcedures、listMaterializedViews）、数据访问（readQuery、writeQuery）、DDL（createDatabase、dropDatabase、dropTable）以及 explainQuery。只读模式会隐藏写入工具（writeQuery、createDatabase、dropDatabase、dropTable）。各后端支持的工具详见 MCP 工具。
• 单二进制文件 — 约 7 MB，无需 Python/Node/Docker
• 多种传输方式 — stdio（用于 Claude Desktop、Cursor）和 HTTP（用于远程/多客户端）
• 双层配置 — CLI 标志 > 环境变量，并为各后端提供合理的默认值
• SSH 隧道 — 通过内置客户端，经由 SSH 堡垒机连接 MySQL/MariaDB/PostgreSQL：支持密码或密钥认证、known_hosts 验证和自动重连

安装 📦

macOS、Linux、WSL：

curl -fsSL https://dbmcp.haymon.ai/install.sh | bash

Windows PowerShell：

irm https://dbmcp.haymon.ai/install.ps1 | iex

Windows CMD：

curl -fsSL https://dbmcp.haymon.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Docker、Cargo 及其他安装方式请参阅安装文档。

快速开始 🚀

使用 .mcp.json（推荐）

在项目根目录添加 .mcp.json 文件。MCP 客户端会读取此文件并自动配置服务。

stdio 传输 — 客户端启动并管理服务进程：

{
  "mcpServers": {
    "dbmcp": {
      "command": "dbmcp",
      "args": ["stdio"],
      "env": {
        "DB_BACKEND": "mysql",
        "DB_HOST": "127.0.0.1",
        "DB_PORT": "3306",
        "DB_USER": "root",
        "DB_PASSWORD": "secret",
        "DB_NAME": "mydb"
      }
    }
  }
}

HTTP 传输 — 由你自行启动服务，客户端连接到该服务：

# Start the server first
dbmcp http --db-backend mysql --db-user root --db-name mydb --port 9001

{
  "mcpServers": {
    "dbmcp": {
      "type": "http",
      "url": "http://127.0.0.1:9001/mcp"
    }
  }
}

注意： HTTP 传输必须设置 "type": "http" 字段。若未设置，Claude Code 等客户端会拒绝此配置。

若要要求使用 bearer 令牌，请通过 HTTP_AUTH_TOKEN 启动服务，并由客户端发送该令牌：

HTTP_AUTH_TOKEN="$(openssl rand -hex 32)" dbmcp http --db-backend mysql --db-user root --db-name mydb

{
  "mcpServers": {
    "dbmcp": {
      "type": "http",
      "url": "http://127.0.0.1:9001/mcp",
      "headers": { "Authorization": "Bearer ${DBMCP_TOKEN}" }
    }
  }
}

使用 CLI 标志

# MySQL/MariaDB
dbmcp stdio --db-backend mysql --db-host localhost --db-user root --db-name mydb

# PostgreSQL
dbmcp stdio --db-backend postgres --db-host localhost --db-user postgres --db-name mydb

# SQLite
dbmcp stdio --db-backend sqlite --db-name ./data.db

# PostgreSQL through an SSH bastion (DB host is resolved by the bastion)
dbmcp stdio --db-backend postgres --db-host db.internal --db-user postgres --db-name mydb \
  --ssh-host bastion.example.com --ssh-user deploy --ssh-key ~/.ssh/id_ed25519

# HTTP transport (loopback only, no token required)
dbmcp http --db-backend mysql --db-user root --db-name mydb --port 9001

# HTTP transport on all interfaces — a bearer token is REQUIRED
HTTP_AUTH_TOKEN=change-me dbmcp http --db-backend mysql --db-user root --db-name mydb --host 0.0.0.0 --port 9001

警告： 绑定非回环地址（例如 --host 0.0.0.0）会使任何能访问该端口的人都能访问数据库。若未设置 HTTP_AUTH_TOKEN，dbmcp 会拒绝启动。Host/Origin 允许列表仅用于防范浏览器 DNS 重绑定攻击——不提供身份验证。

使用环境变量

DB_BACKEND=mysql DB_USER=root DB_NAME=mydb dbmcp stdio

配置 ⚙️

配置按明确的优先级加载：

CLI 标志 > 环境变量 > 默认值

环境变量通常由你的 MCP 客户端设置（通过服务配置中的 env 或 envFile）。

子命令

子命令	描述
stdio	以 stdio 模式运行
http	以 HTTP/SSE 模式运行
version	打印版本信息并退出

必须指定子命令——不带子命令运行 dbmcp 会打印用法帮助，并以非零状态码退出。

数据库选项（所有子命令共用）

标志	环境变量	默认值	说明
--db-backend	DB_BACKEND	（必填）	mysql、mariadb、postgres 或 sqlite
--db-host	DB_HOST	localhost	数据库主机（通过 SSH 隧道时，从 SSH 服务端视角看到的主机）
--db-port	DB_PORT	后端默认值	3306（MySQL/MariaDB）、5432（PostgreSQL）
--db-user	DB_USER	后端默认值	root（MySQL/MariaDB）、postgres（PostgreSQL）
--db-password	DB_PASSWORD	（空）	数据库密码
--db-name	DB_NAME	（空）	数据库名称或 SQLite 文件路径
--db-charset	DB_CHARSET		字符集（仅限 MySQL/MariaDB）

SSL/TLS 选项

标志	环境变量	默认值	说明
--db-ssl	DB_SSL	false	启用 SSL
--db-ssl-ca	DB_SSL_CA		CA 证书路径
--db-ssl-cert	DB_SSL_CERT		客户端证书路径
--db-ssl-key	DB_SSL_KEY		客户端密钥路径
--db-ssl-verify-cert	DB_SSL_VERIFY_CERT	true	验证服务端证书

SSH 隧道选项

标志	环境变量	默认值	说明
--ssh-host	SSH_HOST		SSH 服务端主机；设置后启用隧道
--ssh-port	SSH_PORT	22	SSH 服务端端口
--ssh-user	SSH_USER		SSH 用户名
--ssh-password	SSH_PASSWORD		SSH 密码
--ssh-key	SSH_KEY		SSH 私钥路径（OpenSSH、PKCS#1、PKCS#8、SEC1）
--ssh-key-passphrase	SSH_KEY_PASSPHRASE		SSH 私钥的密码短语
--ssh-known-hosts	SSH_KNOWN_HOSTS	~/.ssh/known_hosts	known_hosts 文件路径（默认：~/.ssh/known_hosts）
--ssh-strict-host-key-checking	SSH_STRICT_HOST_KEY_CHECKING	yes	主机密钥策略：yes 拒绝未知主机，accept-new 在首次连接时信任主机，no 禁用验证（不安全）
--ssh-keepalive-interval	SSH_KEEPALIVE_INTERVAL	30	SSH 保活间隔（秒；设为 0 可禁用）
--ssh-local-port	SSH_LOCAL_PORT	临时端口	本地隧道端口（默认：临时端口）

该隧道仅适用于 MySQL/MariaDB/PostgreSQL，并使用内嵌 SSH 客户端（无需 ssh 二进制文件）。--db-host/--db-port 由 SSH 服务端 解析。如果同时设置了密钥和密码，将优先尝试密钥。有关主机密钥策略、限制和故障排除，请参阅 SSH 隧道。

服务端选项

标志	环境变量	默认值	说明
--db-read-only	DB_READ_ONLY	true	阻止写入查询
--db-max-pool-size	DB_MAX_POOL_SIZE	5	最大连接池大小（最小值：1）
--db-connection-timeout	DB_CONNECTION_TIMEOUT	（未设置）	连接超时时间（秒；最小值：1）
--db-query-timeout	DB_QUERY_TIMEOUT	30	查询执行超时时间（秒）
--db-page-size	DB_PAGE_SIZE	100	分页工具响应中每页的最大项目数（范围：1–500）

日志选项

标志	环境变量	默认值	说明
--log-level	LOG_LEVEL	info	日志级别（trace/debug/info/warn/error）

仅限 HTTP 的选项（仅 http 子命令可用）

标志	默认值	说明
--host	127.0.0.1	绑定主机
--port	9001	绑定端口
--allowed-origins	localhost 变体，任意端口	允许的浏览器来源（以逗号分隔，:* 匹配任意端口）。同时用于 CORS 预检和服务端 Origin 拒绝。
--allowed-hosts	localhost,127.0.0.1,::1	受信任的 Host 标头（以逗号分隔）。由服务端强制执行；HTTP/2 :authority 也会被识别。
--auth-token	(未设置)	每个请求都必须提供的 Bearer 令牌（Authorization: Bearer <token>）。建议使用 HTTP_AUTH_TOKEN 环境变量——CLI 参数可通过 ps 查看。绑定到非回环地址时必需。
--dangerously-allow-unauthenticated	false	允许绑定到非回环地址而不提供令牌（HTTP_DANGEROUSLY_ALLOW_UNAUTHENTICATED）。仅可在由反向代理对调用方进行身份验证时使用。

安全提示：默认的 --allowed-origins 接受来自 localhost/127.0.0.1/[::1] 上任意端口的浏览器页面，因此任何本地 Web 应用都可以调用该服务。在共享或开发机器上，请设置 HTTP_AUTH_TOKEN，或将 --allowed-origins 限定为你信任的明确来源（例如 http://localhost:5173）。

MCP 工具 🧩

listDatabases

列出可访问的数据库，通过 cursor / nextCursor 分页。迭代详情请参阅游标分页。SQLite 不支持此功能。

listTables

列出数据库中的表，通过 cursor / nextCursor 分页。迭代详情请参阅游标分页。

参数：database（默认为当前活动数据库；SQLite 没有 database 参数）、cursor、search、detailed。

search 是可选的、不区分大小写的 LIKE/ILIKE 模式，其中 %（任意序列）和 _（单个字符）是通配符——传入 users% 可匹配以 users 开头的名称，传入 %order% 可进行子字符串匹配。不含通配符的普通词语仅匹配完全相同的表名。

detailed（默认 false）会切换响应结构：

• 简要（默认）——tables 是一个已排序的 JSON 数组，其中包含未包装的表名字符串。
• 详细（detailed: true）——tables 是一个以表名为键的 JSON 对象；每个值包含该表的 schema、kind、owner、comment、columns[]、constraints[]、indexes[] 和 triggers[]。一次调用即可同时返回表列表和每个表的元数据。

listViews

列出数据库中的视图，通过 cursor / nextCursor 分页。MySQL/MariaDB、PostgreSQL（public 架构）和 SQLite 均支持。参数：database（默认为当前活动数据库；SQLite 没有 database 参数）、cursor、search、detailed。SQLite 仅返回简要结构——不接受 search 和 detailed。

search 是可选的、不区分大小写的 LIKE/ILIKE 模式，其中 %（任意序列）和 _（单个字符）是通配符。为保证游标连续性，分页调用中的 search 值必须保持一致。

detailed（默认 false）会切换响应结构：

• 简要（默认）——views 是一个已排序的 JSON 数组，其中包含未包装的视图名称字符串。同一架构内视图名称唯一，因此不会出现重复项。
• 详细（detailed: true）——views 是一个以未包装的视图名称为键的 JSON 对象；每个值包含对应后端的元数据负载。PostgreSQL 提供 schema、owner、description、definition。MySQL/MariaDB 提供 schema、definer、security、checkOption、updatable、characterSetClient、collationConnection、definition。各后端的来源列、枚举值集合和有意省略的内容，请参阅 listViews 参考。

迭代详情请参阅游标分页。

listTriggers

列出用户定义的表触发器，通过 cursor / nextCursor 分页。排除内部约束和外键触发器。适用于 MySQL/MariaDB、PostgreSQL（public 架构）和 SQLite。参数：database（默认为当前活动数据库；SQLite 没有 database 参数）、cursor、search、detailed。

search 是可选的不区分大小写的 LIKE / ILIKE 模式，其中 %（任意序列）和 _（单个字符）是通配符。为确保游标连续性，分页调用中的 search 值必须保持一致。

detailed（默认为 false）用于切换响应结构：

• 简要（默认）——triggers 是一个已排序的 JSON 数组，其中仅包含触发器名称字符串。
• 详细（detailed: true）——triggers 是一个以触发器名称为键的 JSON 对象；每个值都包含对应后端的元数据负载（时机、事件、定义，以及 PostgreSQL 的 status / functionName 或 MySQL/MariaDB 会话上下文字段等后端特有的额外信息）。各后端的完整字段列表请参阅 listTriggers 参考文档。

迭代详情请参阅游标分页。

listFunctions

列出用户定义的 SQL 函数，通过 cursor / nextCursor 分页。PostgreSQL 会排除聚合函数、窗口函数和存储过程；MySQL/MariaDB 会排除可加载的 UDF（mysql.func）。适用于 MySQL/MariaDB 和 PostgreSQL（public 架构）。SQLite 不支持。参数：database（默认为当前活动数据库）、cursor、search、detailed。

search 是可选的不区分大小写的 LIKE / ILIKE 模式，其中 %（任意序列）和 _（单个字符）是通配符。为确保游标连续性，分页调用中的 search 值必须保持一致。

detailed（默认为 false）用于切换响应结构：

• 简要（默认）——functions 是一个已排序的 JSON 数组，其中仅包含函数名称字符串。PostgreSQL 的重载函数会按每个重载分别出现一次（名称字符串重复是预期行为）。
• 详细（detailed: true）——functions 是一个以函数签名为键的 JSON 对象；每个值都包含对应后端的元数据负载（语言、参数、返回类型、定义，以及 PostgreSQL 的 volatility / strict / parallelSafety 或 MySQL/MariaDB 会话上下文字段等后端特有的额外信息）。PostgreSQL 的键格式为 name(arguments)（用于区分重载）；MySQL/MariaDB 的键为纯名称（不支持重载）。各后端的完整字段列表请参阅 listFunctions 参考文档。

迭代详情请参阅游标分页。

listProcedures

列出用户定义的存储过程，通过 cursor / nextCursor 分页。适用于 MySQL/MariaDB 和 PostgreSQL（public 模式，PostgreSQL 11+）。SQLite 不支持。参数：database（默认为当前活动数据库）、cursor、search、detailed。

search 是可选的、大小写不敏感的 LIKE/ILIKE 模式，使用 %（任意序列）和 _（单个字符）作为通配符。为确保游标连续性，分页调用中的 search 值必须保持一致。

detailed（默认为 false）会切换响应结构：

• 简要（默认）——procedures 是一个按排序排列的 JSON 数组，其中包含未修饰的过程名称字符串。PostgreSQL 的重载会按每个重载分别出现一次（预期会有重复的名称字符串）。
• 详细（detailed: true）——procedures 是一个以过程签名为键的 JSON 对象；每个值都包含对应后端的元数据（语言、参数、安全性、定义，以及特定于后端的额外信息，例如 PostgreSQL 的 owner，或 MySQL/MariaDB 的 deterministic/sqlDataAccess/会话上下文字段）。PostgreSQL 的键为 name(arguments)（重载使用不同键；零参数过程的键为 name()）；MySQL/MariaDB 的键为未修饰的名称（不支持重载）。各后端字段的完整列表，请参阅 listProcedures 参考。

迭代详情请参阅游标分页。

listMaterializedViews

列出 public 模式中的物化视图，通过 cursor / nextCursor 分页。仅适用于 PostgreSQL——MySQL/MariaDB 和 SQLite 不支持。参数：database（默认为当前活动数据库）、cursor、search、detailed。

search 是可选的、大小写不敏感的 ILIKE 模式，使用 %（任意序列）和 _（单个字符）作为通配符。SQL 元字符（'、;、--）会作为参数值绑定，绝不会插入到查询中。为确保游标连续性，分页调用中的 search 值必须保持一致。

detailed（默认为 false）会切换响应结构：

• 简要（默认）——materializedViews 是一个按排序排列的 JSON 数组，其中包含未修饰的物化视图名称字符串。物化视图名称在每个模式中都是唯一的，因此不会出现重复项。
• 详细（detailed: true）——materializedViews 是一个以未修饰的物化视图名称为键的 JSON 对象；每个值都包含 schema、owner、description（若没有 COMMENT ON MATERIALIZED VIEW，则为 null）、definition（pg_matviews.definition 中逐字返回的 SELECT 主体）、populated（对于使用 WITH NO DATA 创建且从未刷新过的物化视图，此值为 false），以及 indexed（存在至少一个索引时为 true；REFRESH MATERIALIZED VIEW CONCURRENTLY 还要求有唯一索引）。详细模式有意省略列元数据、tablespace、存储参数和唯一索引检测；这些信息可通过 definition、listTables(detailed=true) 或查询 pg_indexes 的 readQuery 获取。源列和操作语义请参阅 listMaterializedViews 参考。

迭代详情请参阅游标分页。

readQuery

执行只读 SQL 查询（SELECT、SHOW、DESCRIBE、USE、EXPLAIN）。始终强制执行 SQL 验证，作为纵深防御。参数：query、database、cursor。SELECT 结果通过 cursor / nextCursor 分页；SHOW、DESCRIBE、USE 和 EXPLAIN 只返回单页，并忽略 cursor。迭代详情请参阅游标分页。

writeQuery

执行写入类 SQL 查询（INSERT、UPDATE、DELETE、CREATE、ALTER、DROP）。仅在禁用只读模式时可用。参数：query、database。

createDatabase

如果数据库不存在，则创建该数据库。仅在禁用只读模式时可用。SQLite 不支持。参数：database。

dropDatabase

删除现有数据库。拒绝删除当前已连接的数据库。仅在禁用只读模式时可用。SQLite 不支持。参数：database。

dropTable

从数据库中删除表。如果该表存在外键依赖项，数据库错误会显示给用户。在 PostgreSQL 上，可使用 cascade 参数强制执行带 CASCADE 的删除操作。仅在禁用只读模式时可用。参数：database、table、cascade（仅限 PostgreSQL）。

explainQuery

返回 SQL 查询的执行计划。支持可选的 analyze 参数，用于获取实际执行统计信息（PostgreSQL 和 MySQL/MariaDB）。在只读模式下，仅允许对只读语句执行 EXPLAIN ANALYZE，因为它会实际执行查询。SQLite 使用 EXPLAIN QUERY PLAN（不支持 ANALYZE）。无论只读模式如何，始终可用。参数：query、database、analyze（仅限 PostgreSQL/MySQL）。

安全 🔒

• 只读模式（默认）——对 AI 助手隐藏写入工具；readQuery 会强制执行基于 AST 的 SQL 验证
• 单语句强制限制——在解析阶段拦截多语句注入
• 危险函数拦截——在 AST 中检测 LOAD_FILE()、INTO OUTFILE、INTO DUMPFILE
• 标识符验证——根据控制字符和空字符串验证数据库名/表名
• HTTP bearer 身份验证——HTTP_AUTH_TOKEN 强制要求 Authorization: Bearer <token>（使用恒定时间比较；验证失败时返回 401）；绑定到非环回地址时，若未提供令牌则拒绝启动
• Origin 和 Host 允许列表——服务端拒绝请求（403），并支持 CORS 预检；可针对 HTTP 传输进行配置。可防御浏览器 DNS 重绑定攻击，但不能替代身份验证
• SSL/TLS——通过单独的 DB_SSL_* 变量配置
• SSH 主机密钥验证——SSH 隧道会使用 known_hosts 验证服务端密钥（默认值为 yes）；绝不会记录 SSH 密码和口令
• PII 脱敏（选择启用，默认关闭）——启用后，查询工具输出会经过基于正则表达式的脱敏器处理，对检测到的 PII 片段进行重写。该脱敏器内置 46 种实体类型，涵盖七类：个人信息（电子邮件）、财务信息（银行卡、IBAN、英国银行账户、SORT 和美国 ABA 路由代码、CVV）、政府证件号（SSN、ITIN、EIN、英国/美国护照、NHS、NINO、SIN、VAT）、联系方式（电话号码）、网络信息（IP、URL、MAC）、数字身份信息（API 密钥、JWT、PEM 私钥、密码哈希）和加密货币钱包。开关：--pii / PII_ENABLE。处理方式：--pii-operator / PII_OPERATOR——可选 replace（默认值，使用 <EMAIL_ADDRESS> 等与实体类型对应的占位符）、mask（使用 *，保持原长度）、redact（删除）、hash（SHA-256 十六进制值）。可通过 --pii-categories / PII_CATEGORIES 选择子集（逗号分隔，例如 financial,government）；未设置时启用所有内置类别。范围：仅限查询工具输出负载。完整配置请参阅 PII configuration。
• ML/NER 脱敏（运行时选择启用，默认关闭）——新增对正则表达式无法捕获的 PERSON、LOCATION、ORGANIZATION、NATIONALITY_RELIGION_POLITICS 和 FACILITY 的检测；通过 --pii-ner / PII_NER_ENABLE 开关以及用户提供的模型目录启用。可检测的实体取决于模型的标签（CoNLL 模型可检测人员/地点/组织；OntoNotes 类模型还可检测 NRP 和设施）。推理使用 ONNX Runtime（模型目录包含 config.json、tokenizer.json、model.onnx；推荐使用 MIT 许可的 dslim/bert-base-NER，将其导出为 ONNX 并进行 int8 量化以提升速度）。故障时采取关闭策略：无法加载模型时会中止启动，推理出错时会使请求失败——绝不会静默回退。遵循 --pii-categories 的设置。v1 仅支持英文。
• 凭证脱敏——日志和调试输出中绝不显示数据库密码

测试 🧪

# Unit tests
cargo test --workspace --lib --bins

# Integration tests (requires Docker)
./tests/run.sh

# Filter by engine
./tests/run.sh --filter mariadb
./tests/run.sh --filter mysql
./tests/run.sh --filter postgres
./tests/run.sh --filter sqlite

# With MCP Inspector
npx @modelcontextprotocol/inspector ./target/release/dbmcp stdio

# HTTP mode testing
curl -X POST http://localhost:9001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}'

项目结构 🗂️

这是一个 Cargo 工作区，包含以下 crate：

Crate	路径	描述
dbmcp	.（根目录）	二进制垫片
dbmcp-cli	crates/cli/	CLI 解析、传输和服务启动
dbmcp-sql	crates/sql/	共享错误类型、验证和标识符工具
dbmcp-config	crates/config/	配置结构体和验证
dbmcp-server	crates/server/	共享 MCP 工具实现和服务信息
dbmcp-mysql	crates/mysql/	MySQL/MariaDB 后端处理器和操作
dbmcp-postgres	crates/postgres/	PostgreSQL 后端处理器和操作
dbmcp-sqlite	crates/sqlite/	SQLite 后端处理器和操作
dbmcp-pii	crates/pii/	查询输出中的 PII 检测和匿名化
dbmcp-sql-lineage	crates/sql-lineage/	列级 SQL 血缘提取
dbmcp-ssh	crates/ssh/	数据库连接的 SSH 隧道
sqlx-json	crates/sqlx-json/	sqlx 的类型安全行转 JSON 转换（RowExt trait）

开发 🧰

cargo build              # Development build
cargo build --release    # Release build (~7 MB)
cargo test               # Run tests
cargo clippy --workspace --tests -- -D warnings  # Lint
cargo fmt                # Format
cargo doc --no-deps      # Build documentation

许可证 📄

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