custom-mcp-database

自定义 MCP 数据库

mcp-name: io.github.renanlido/custom-mcp-database

一个 MCP 服务，可让 AI Agent 对 PostgreSQL、MySQL、MongoDB 和 Oracle 执行基于别名的查询，且绝不会向模型暴露凭据。连接只需配置一次，并存储在本地；Agent 始终只通过别名引用连接。

适用于 Claude Code、Claude Desktop、Cursor、VS Code、Windsurf、Gemini CLI 以及任何其他 MCP 客户端（它们都使用相同的 stdio 启动命令）。

---

快速开始

这里特意区分了两种角色。将它们分开，才能确保数据库密码永远不会传给模型。

你（在终端中操作一次）——安装凭据

**Agent 不会安装凭据。**你需要使用 CLI 操作。密钥保留在你的机器上，绝不会发送给模型。

最简单的方式——使用引导式向导（询问类型、主机、用户以及如何提供密钥；还可选择测试连接）：

uvx custom-mcp-database setup

或者用一行命令完成（系统会提示输入密码，输入内容不会显示）：

uvx custom-mcp-database add-db --alias prod_ro --type postgres \
  --host db.internal --port 5432 --user reporting --dbname app

uvx custom-mcp-database list-aliases   # confirm it's there

Agent（始终如此）——通过别名使用连接

将 MCP 客户端指向此服务（参见安装），然后直接提出请求：

“使用 prod_ro，运行 SELECT count(*) FROM orders。”

Agent 会使用别名 prod_ro 调用 db_execute_query，而不会使用主机、用户或密码。它在物理层面上无法看到凭据；凭据存储在本地配置中，仅在查询时于服务进程内部解析。

**为什么 Agent 不能添加数据库：**MCP 工具的参数由大模型生成并读取。如果 Agent 将你的密码输入 add 工具，密码就会进入模型上下文、服务提供商和日志。因此，凭据设置在设计上必须由人通过 CLI 完成。（需要 Agent 在自动化流水线中配置连接？请参阅 SECURITY.md 中的 MCP_DB_ALLOW_ADMIN_TOOLS——即便启用，它也只接受密钥的引用，例如环境变量名，而不会接受密钥本身。）

默认情况下禁用写入（只读）。如需在某项任务中允许写入： export MCP_DB_READONLY=0 MCP_DB_ALLOW_WRITES=1。

---

安装

该服务通过 stdio 运行。通用启动命令为 uvx custom-mcp-database run（需要安装 uv；首次运行时会从 PyPI 获取此软件包）。

Claude Code

# Direct (published package)
claude mcp add custom-mcp-database -- uvx custom-mcp-database run

# Or install the full plugin from this repo's marketplace
/plugin marketplace add renanlido/custom-mcp-database
/plugin install custom-mcp-database@renanlido-mcp

Claude Desktop

有两种方式：

1. 一键安装包——构建 .mcpb（mcpb pack），然后在 Claude Desktop 中打开。请参阅分发。
2. 手动配置——将 examples/mcp-clients/claude-desktop.json 中的代码片段添加到 claude_desktop_config.json。

其他客户端

复制匹配的代码片段——它们都使用相同的 command/args，只有文件和键名不同：

客户端	配置文件	键	代码片段
Cursor	~/.cursor/mcp.json	mcpServers	cursor.json
VS Code	.vscode/mcp.json	servers	vscode.json
Windsurf	~/.codeium/windsurf/mcp_config.json	mcpServers	windsurf.json
Gemini CLI	~/.gemini/settings.json	mcpServers	gemini-cli.json

完整的客户端列表及本地检出版本配置示例：examples/mcp-clients/README.md。

---

配置连接

使用 CLI 在终端中配置连接 — 切勿通过 Agent 配置。 连接密码是真正的机密；如果将它作为 MCP 工具参数传递，它就会进入模型上下文（以及服务提供商、对话记录和日志）。因此，凭据管理工具默认不会通过 MCP 暴露；配置连接是人工通过 CLI 完成的任务。Agent 只能列出并使用别名。

省略 --password/--uri，即可通过安全提示输入（输入会隐藏，也不会存入 shell 历史记录）。更好的做法是通过 --password-env / --password-file 将机密完全排除在配置文件之外（在连接时解析）：

# PostgreSQL — prompted for the password (recommended)
uvx custom-mcp-database add-db --alias pg --type postgres \
  --host localhost --port 5432 --user me --dbname app

# MySQL — password taken from an env var at connect time (nothing secret on disk)
MYSQL_PW=... uvx custom-mcp-database add-db --alias my --type mysql \
  --host localhost --port 3306 --user root --dbname app --password-env MYSQL_PW

# Oracle — password read from a file (e.g. a mounted secret)
uvx custom-mcp-database add-db --alias ora --type oracle \
  --host db.example.com --port 1521 --user system --dbname ORCLPDB1 \
  --password-file /run/secrets/ora_pw

# MongoDB — full URI from a file (the URI embeds credentials)
uvx custom-mcp-database add-db --alias mongo --type mongo \
  --dbname app --uri-file /run/secrets/mongo_uri

uvx custom-mcp-database list-aliases
uvx custom-mcp-database remove-db --alias pg

配置文件位置（可通过 MCP_DB_CONFIG 覆盖）： $XDG_CONFIG_HOME/custom-mcp-database/mcp_config.sqlite3 （默认路径为 ~/.config/custom-mcp-database/mcp_config.sqlite3，权限为 0600）。

如果传入字面值 --password/--uri，它们会以明文 JSON形式存储在该 SQLite 文件中。建议使用 --password-env/--password-file（或 --uri-env/--uri-file），这样文件中只会存储引用。无论哪种方式，都要妥善保护该文件（权限为 0600，已加入 gitignore，且未加密）。

---

MCP 工具

工具	用途
db_list_aliases	列出已配置的别名和类型
db_execute_query	执行 SQL 或 MongoDB JSON 筛选条件
db_list_collections	列出 MongoDB 集合
db_security_status	报告当前生效的安全策略

默认情况下，db_add_database / db_remove_database 不会通过 MCP 暴露 — 请使用 CLI 管理连接。若要选择启用这些工具（添加工具只接受以引用形式提供的机密，绝不接受明文密码），请设置 MCP_DB_ALLOW_ADMIN_TOOLS=1。

db_execute_query 说明：SQL 按原样执行，并使用参数化绑定（请自行添加 LIMIT）；MongoDB 接受 JSON 筛选条件和 collection，结果上限为 10 条（--limit），拒绝空筛选条件，并将 24 字符的十六进制字符串转换为 ObjectId。

---

安全

此服务会处理真实凭据和生产数据，因此默认采用拒绝优先策略：

• 默认只读。 只允许执行 SELECT 类 SQL。写入和 DDL 操作需要明确选择启用。
• 禁止堆叠语句（阻止通过 ; 注入），每次调用只执行一条语句。
• 禁止 MongoDB 服务端 JavaScript（$where、$function、$accumulator、mapReduce 等）。
• 校验标识符（不能利用 oracle_schema 进行注入）。
• 限制结果数量，上限为 MCP_DB_MAX_ROWS（默认值为 1000）；从错误信息中清除机密。
• 凭据存储采用权限为 0600 的明文 SQLite 文件 — 请确保主机磁盘已加密。

查看当前安全状态：custom-mcp-database security-status（或使用 db_security_status 工具）。

为特定任务启用写入（完成后再关闭）：

export MCP_DB_READONLY=0
export MCP_DB_ALLOW_WRITES=1     # INSERT/UPDATE/DELETE
# export MCP_DB_ALLOW_DDL=1      # only if you really need CREATE/DROP/ALTER/...

请在 SECURITY.md 中阅读完整协议 — 内容涵盖最小权限数据库角色、TLS、提示词注入处理和漏洞报告。 应用层防护提供纵深防御；权威控制措施是使用遵循最小权限原则的数据库账户。

开发

uv sync                 # create .venv and install deps
make run                # run the server (stdio)
make lint               # ruff
make build              # sdist + wheel into dist/

交互式检查工具：

uv run mcp dev src/custom_mcp_database/server.py

---

发布

此仓库为所有主要渠道提供可直接发布的元数据。所有内容都会在推送到 main 时自动发布（见下文）：

渠道	文件	发布方式
PyPI	pyproject.toml	release.yml（推送到 main 时）
MCP 注册表	server.json	release.yml（推送到 main 时）
Claude Code 插件	.claude-plugin/plugin.json、.mcp.json	推送到 GitHub 后即可使用
Claude Code 市场	.claude-plugin/marketplace.json	推送到 GitHub 后即可使用
Claude Desktop 捆绑包	manifest.json	release.yml 会将 .mcpb 附加到 Release 中

自动发布——只需推送到 main

发布流程完全自动化。每次推送到 main 时， .github/workflows/release.yml 都会：

1. 根据上一个标签之后的提交，确定下一个语义化版本（feat: → 次版本号，BREAKING CHANGE/type!: → 主版本号，其他情况 → 修订号；在提交信息中添加 [skip release] 可跳过发布）。
2. 将该版本写入 pyproject.toml，并通过 scripts/sync_version.py 同步到每个构建产物（server.json、manifest.json、插件和市场）；版本号只需在一处维护，无需手动更新。
3. 构建并提交 chore(release): vX [skip ci]，创建 vX 标签并推送。
4. 发布到 PyPI（Trusted Publishing/OIDC），然后发布到 MCP Registry（GitHub OIDC）。
5. 打包 .mcpb，并创建附带 wheel 和 bundle 的 GitHub Release。

发布提交包含 [skip ci]，因此不会再次触发工作流。

一次性设置（无法自动完成——需要使用你的账号）：

• 为 renanlido/custom-mcp-database 创建一个 PyPI Trusted Publisher，工作流设为 release.yml。
• 允许 GitHub Actions 推送到 main（仓库 → Settings → Actions → Read and write permissions；如果 main 是受保护分支，请允许 actions bot 绕过保护，或使用 PAT）。

MCP Registry 命名空间为 io.github.renanlido/custom-mcp-database（已通过 GitHub 验证）。

本地手动备用方案：运行 make build（同步版本并构建），然后运行 uv publish。

---

许可证

MIT