内容
# mcp-multi-db
[](https://www.npmjs.com/package/mcp-multi-db)
[](https://www.npmjs.com/package/mcp-multi-db)
[](LICENSE)
[](https://glama.ai/mcp/servers/mahAnuj/mcp-multi-db)
**适用于所有 SQL 数据库的单个 MCP 服务器 - 默认情况下只读且安全。**
[](https://glama.ai/mcp/servers/mahAnuj/mcp-multi-db)
通过单个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，将 AI 代理连接到 PostgreSQL、MySQL 和 SQLite。同时在配置文件中列出数据库，代理通过 `database_id` 选择要查询的数据库。每个查询都在数据库级别强制为只读，因此可以安全地指向真实数据。
- **多引擎，单服务器** - Postgres、MySQL 和 SQLite 并存；每个数据库无需单独的服务器。
- **默认只读和安全** - 两层强制（SQL 文本保护 + 数据库级只读事务）以及行限制和查询超时。参见 [安全.md](SECURITY.md)。
- **架构感知** - 代理可以在编写查询之前发现数据库、表/视图和列元数据。
- **零查询语言需要学习** - 只需用自然语言询问。
> 该剪辑通过 stdio（使用 MCP SDK）驱动实际服务器，针对预先准备的 SQLite 数据库。可以使用 `npm run build && vhs examples/demo.tape` 重新生成。
## 工具
| 工具 | 描述 |
|------|-------------|
| `list_databases` | 列出已配置的数据库连接 |
| `list_tables` | 列出数据库中的表/视图 |
| `describe_table` | 显示表的列元数据 |
| `run_query` | 运行只读 SQL（`SELECT`、`WITH`、`EXPLAIN`） |
## 快速入门
无需安装 - `npx` 在首次使用时获取包。
### 1. 创建 `databases.json`
复制示例并使用您的连接详细信息进行编辑：
```bash
cp databases.example.json databases.json
```
```json
{
"databases": [
{
"id": "local-sqlite",
"type": "sqlite",
"path": "/absolute/path/to/app.db",
"label": "本地开发 SQLite"
},
{
"id": "analytics-pg",
"type": "postgres",
"connectionString": "postgresql://user:pass@localhost:5432/analytics",
"label": "分析仓库"
},
{
"id": "reporting-mysql",
"type": "mysql",
"connectionString": "mysql://user:pass@localhost:3306/reporting",
"label": "报告 MySQL"
}
]
}
```
> **永远不要提交 `databases.json`** - 它包含凭证。如果您克隆了存储库，它已经在 `.gitignore` 中。优先使用只读数据库用户（参见 [安全](#安全)）。
### 2. 将服务器注册到您的 MCP 客户端
服务器通过 **stdio** 说话 MCP，因此它适用于任何支持 MCP 的客户端。使用 `npx mcp-multi-db` 作为命令，并传递 `MCP_DB_CONFIG`（您的 `databases.json` 的路径）。参见 [mcp.example.json](mcp.example.json) 和 [databases.example.json](databases.example.json) 以获取模板。
<details open>
<summary><b>Claude Desktop</b></summary>
编辑 `claude_desktop_config.json`（macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"mcp-multi-db": {
"command": "npx",
"args": ["-y", "mcp-multi-db"],
"env": {
"MCP_DB_CONFIG": "/absolute/path/to/databases.json"
}
}
}
}
```
重启 Claude Desktop 后。
</details>
<details>
<summary><b>Claude Code</b></summary>
```bash
claude mcp add mcp-multi-db \
--env MCP_DB_CONFIG=/absolute/path/to/databases.json \
-- npx -y mcp-multi-db
```
</details>
<details>
<summary><b>Cursor</b></summary>
添加到 `~/.cursor/mcp.json`（或项目中的 `.cursor/mcp.json`），然后打开 **Cursor 设置 → 工具和 MCP**，重启服务器并使用 **代理** 模式：
```json
{
"mcpServers": {
"mcp-multi-db": {
"command": "npx",
"args": ["-y", "mcp-multi-db"],
"env": {
"MCP_DB_CONFIG": "/absolute/path/to/databases.json"
}
}
}
}
```
</details>
<details>
<summary><b>Cline / Windsurf / 其他 MCP 客户端</b></summary>
任何支持 stdio MCP 服务器的客户端都使用相同的格式：命令 `npx`，参数 `["-y", "mcp-multi-db"]`，以及指向您的 `databases.json` 的环境变量 `MCP_DB_CONFIG`。请参阅您客户端的文档，了解其 MCP 配置的位置。
> **更喜欢固定的全局安装？** `npm install -g mcp-multi-db`，然后使用命令 `mcp-multi-db` 而不带参数。
</details>
## 配置参考
配置从以下两个环境变量之一加载，按顺序排列：
1. **`MCP_DB_CONFIG`** - JSON 文件的路径（推荐）。
2. **`MCP_DATABASES`** - 内联 JSON（当文件路径不方便时）。
JSON 可以是 `{ "databases": [ ... ] }` 或一个裸数组。每个条目：
| 字段 | 必需 | 备注 |
|-------|----------|-------|
| `id` | 是 | 唯一；代理引用此作为 `database_id` |
| `type` | 是 | `postgres` \| `mysql` \| `sqlite` |
| `connectionString` | postgres/mysql | 标准连接 URI |
| `path` | sqlite | `.db` 文件的绝对路径 |
| `label` | 否 | 显示给代理的友好名称 |
| `description` | 否 | 显示给代理的额外上下文 |
## 示例提示
- "列出我的已配置数据库"
- "`local-sqlite` 中有哪些表？"
- "描述 `analytics-pg` 中的 `users` 表"
- "在 `reporting-mysql` 上运行 `SELECT COUNT(*) FROM orders`"
## 安全
- **仅只读。** `INSERT`、`UPDATE`、`DELETE`、DDL 等被阻止 - 既通过 SQL 文本保护，也通过在数据库级事务中运行每个查询（SQLite 打开只读）。调用有副作用的函数的 `SELECT` 仍然被拒绝。
- **行限制。** 结果被限制（默认 100，最大 1000）。
- **查询超时。** 语句被限定（30s）以避免失控查询。
- **无论如何，请使用最小权限。** 优先使用专用的只读 DB 用户和只读副本。完整的详细信息和报告在 [安全.md](SECURITY.md)。
## Docker
包含一个多阶段的 [`Dockerfile`](Dockerfile)。使用您的 `databases.json` 挂载构建和运行：
```bash
docker build -t mcp-multi-db .
docker run --rm -i \
-v /absolute/path/to/databases.json:/config/databases.json:ro \
mcp-multi-db
```
镜像以非 root 用户运行，仅包含构建的 JS 和运行时 `node_modules`（无工具链），并且通过 stdio 说话 MCP，就像 npx 安装一样 - 因此可以通过替换命令和参数与适当的 `docker run -i` 调用来适配任何 MCP 客户端。
## 开发
```bash
npm install
npm run build # tsc -> build/，MCP 客户端运行的工件
npm test # 构建，然后运行 node:test 套件
```
测试使用 Node 内置的测试运行器（无额外依赖）并涵盖只读 SQL 保护和 SQLite 适配器端到端。CI 在每次推送和拉取请求上运行构建 + 测试。
添加另一个数据库引擎是一个受限的更改：在 [`src/config.ts`](src/config.ts) 中添加配置变体，在 [`src/adapters/`](src/adapters/) 下的新适配器中实现 `SqlDatabasePort` 接口，并在适配器工厂中注册它。新适配器必须在连接级别强制只读 - 而不仅仅依赖文本保护。有关完整的检查清单，请参见 [docs/extending.md](docs/extending.md)。
## 文档
- **[架构](docs/architecture.md)** - 组件、请求生命周期和端口系列设计（带图表）。
- **[扩展](docs/extending.md)** - 添加 SQL 引擎或非 SQL 系列。
- **[安全](SECURITY.md)** - 两层只读模型和安全部署。
完整索引在 [docs/](docs/README.md)。
## 许可证
ISC - 参见 [LICENSE](LICENSE)。
