Database MCP

@cocaxcode/database-mcp

只需一段对话，即可访问你的数据库。
33 个工具 · PostgreSQL · MySQL · SQLite · 连接组 · 回滚 · 导出/恢复 · 自动发现架构

概览 · 直接对话 · 连接组 · 安装 · 功能 · 工具参考 · 存储 · 架构

快速概览

功能最全面的数据库 MCP 服务。提供 33 个工具，支持 3 种数据库引擎（PostgreSQL、MySQL、SQLite），并具备连接组、命名连接管理、自动回滚、导出/恢复、通过 MCP Resources 自动发现架构以及完整的查询历史记录——全部通过自然语言操作。

这不仅仅是一个查询运行器，更是一套完整的数据库工作台：将连接整理到与项目目录绑定的组中，设置可跨会话保留的默认值，以三种详细程度检查架构，为每次写入操作创建变更前快照，通过反向 SQL 撤销错误，导出和恢复整个数据库，并按项目和连接追踪你运行的每条查询。

每个连接都属于一个组。组具有作用范围（目录）、默认连接和活动连接。在作用范围内的目录中工作时，你只会看到该组的连接——不会杂乱，也不会混淆。

描述你的需求即可。AI 会读取你的架构、编写 SQL，并安全地执行——自动注入 LIMIT、创建变更前快照，并在执行破坏性操作前请求确认。无需云账户、ORM 或配置文件。凭据绝不会离开你的设备。一切都在本地运行。

适用于 Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Codex CLI、Gemini CLI 以及任何兼容 MCP 的客户端。

直接对话

你无需记住工具名称或 SQL 语法，只需说出你的需求。

> "Connect to my local PostgreSQL on port 5432, database myapp, user admin"

> "Create a group called backend and add this directory"

> "Connect to my PostgreSQL on localhost, put it in the backend group"

> "Set local-pg as the default connection"

> "Show me all tables"

> "What columns does the users table have?"

> "Show me the last 10 orders with the customer name"
  -> AI reads FKs from schema, builds the JOIN, applies LIMIT 10

> "Insert a test user called Alice"
  -> Snapshot captured for rollback

> "Oops, undo that"
  -> Rows restored via reverse SQL

> "Switch to the production database for this session"
  -> Instant context change, all queries now go to prod

> "Delete all inactive users"
  -> "This will affect N rows. Call again with confirm=true to proceed."

> "What did I run today?"
  -> Full query history with timestamps and execution times

> "Dump the database — structure and data"
  -> SQL file generated, ready for restore

AI 已经通过 MCP Resources 了解你的架构。它会读取 db://schema 来发现表，并读取 db://tables/{name}/schema 来获取列、外键和索引。当你要求查询多个表中的数据时，它会自动构建正确的 JOIN。

连接组

每个连接都属于一个组。组是组织数据库连接的单元，可让连接各自归属清晰、井然有序并自动管理。

一个组有三个关键概念：

• 作用域：共享该组连接的目录。在作用域目录中工作时，你只能看到该组的连接，不会被全局内容干扰。
• 默认连接：进入作用域目录时自动激活的连接。会在会话之间保留。
• 当前连接：此刻正在使用的连接。仅对当前会话有效，重启后会重置为默认连接。

以下是一个实用工作流：

"Create a group called backend"
"Add this directory as scope"
"Create a PostgreSQL connection called local-dev in the backend group"   <- auto-default (first connection)
"Create another called production in backend"
"List connections"                                                       <- shows local-dev (active, default)
"Switch to production"                                                   <- session only
"Set production as default"                                              <- persists between sessions

添加到组中的第一个连接会自动成为默认连接。切换连接只会更改当前会话中正在使用的连接；重启后会恢复为默认连接。若要让更改持续生效，请明确设置新的默认连接。

这意味着，你可以放心地临时切换到生产环境执行快速查询，并且知道下次打开项目时，会回到开发数据库。

安装

Claude Code

claude mcp add --scope user database -- npx -y @cocaxcode/database-mcp@latest

Claude Desktop

将以下内容添加到配置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

{
  "servers": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

codex mcp add database -- npx -y @cocaxcode/database-mcp@latest

[mcp_servers.database]
command = "npx"
args = ["-y", "@cocaxcode/database-mcp@latest"]

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

安装驱动程序

只安装所需的驱动程序；它们会在运行时动态加载：

npm install -g postgres       # PostgreSQL (postgres.js)
npm install -g mysql2         # MySQL
npm install -g sql.js         # SQLite (runs in-process, no native bindings)

注意： 使用 npx 时，驱动程序必须全局安装。如果将服务全局安装（npm install -g @cocaxcode/database-mcp），驱动程序可以本地或全局安装。

功能

一个界面，管理多个数据库

大多数数据库 MCP 服务都要求你在每个会话中重新配置凭据。本服务无需如此。命名连接会保存在组中；创建一次，即可永久使用。

命名连接的工作方式类似于 git 分支。 在组中创建一次 dev、staging、prod，它们就会一直存在。切换即时完成，只需一条命令，无需重新配置：

"Create a group called my-project and add this directory as scope"
"Create a connection called dev with host localhost, database myapp, user admin in my-project"
"Create a read-only connection called analytics pointing to ./data/metrics.db in my-project"
"Switch to dev"               -> queries go to PostgreSQL
"Switch to analytics"         -> queries go to SQLite
"Duplicate dev as dev-readonly with read-only mode"

按组作用域划分的连接意味着不同项目会自动使用不同的数据库。在项目 A 中工作？你会看到项目 A 的组及其连接。切换到项目 B 的目录后，就会自动使用项目 B 的组及其默认连接。无需手动切换，项目之间也不会相互干扰：

"Create a group called frontend with scope /home/user/frontend"
"Create a group called backend with scope /home/user/backend"

现在，每个目录都有一组独立的连接。

凭据 100% 保存在本地。 每个连接都以 JSON 文件的形式存储在 ~/.database-mcp/connections/ 中。密码不会离开你的机器。不会向云端发送任何内容，也不会提交到 git。凭据完全由你掌控。

实时管理。 可在对话过程中创建、复制、重命名、测试、导出和切换连接。无需重启，无需编辑配置文件，也不会丢失上下文。

内置安全保护

回滚快照

每次变更都会捕获变更前的状态快照。撤销任何操作。

"Show me available rollbacks"
"Rollback the last delete"
  -> "This will INSERT 47 rows back into orders. Confirm?"
  -> Rows restored via reverse SQL

架构内省

三个详细程度级别，并支持模式筛选：

"List all tables"                         -> names only (fast)
"Show me the users table with columns"    -> columns + types + nullable
"Full schema for orders including FKs"    -> columns + foreign keys + indexes
"Tables starting with user"              -> pattern: 'user%'

MCP 资源（db://schema 和 db://tables/{name}/schema）可让 AI Agent 自动访问你的架构，无需手动编写 SQL 即可执行多表查询。

使用 EXPLAIN 执行查询

"Show me all users"
  -> SELECT * FROM users LIMIT 100         <- auto LIMIT

"Show the execution plan for this query"
  -> EXPLAIN ANALYZE with dialect-specific syntax (PostgreSQL/MySQL/SQLite)

压缩模式（v0.3+）

SQL 结果通常包含 TEXT / JSON / HTML 列，每行可能达到数 KB。AI Agent 需要为进入上下文窗口的每个字节付费。execute_query、execute_mutation 和 explain_query 接受四个可选参数，在保持行和结构完整的同时，可减少 60-95% 的令牌消耗。

模式：

• minimal — 仅返回 rowCount、executionTimeMs、affectedRows 以及首行预览。非常适合确认 INSERT/UPDATE/DELETE 操作、COUNT 查询和轮询。可节省约 90-95% 的令牌。
• normal（默认）— 返回完整行，但每个单元格会截断至 max_cell_bytes，并附加 …(+NB) 标记。保留表格结构。对于宽行，可节省约 60-80% 的令牌。
• full — 完整返回结果，不做任何处理。需要每个单元格的完整值时使用。

对 SELECT * FROM blog_posts LIMIT 100 的典型节省量：其中 content 每行约含 2KB HTML（总计约 200KB）：

如需查看与原始 psql 的实测数据对比，请参阅下文的原生替代方案。

恢复完整结果： 每个压缩后的响应都包含一个 call_id。如需稍后获取完整单元格内容，请调用 inspect_last_query({ call_id }) — 无需重新执行 SQL，即可避免增加数据库负载并触发任何副作用。结果会保存在一个含 20 个槽位的环形缓冲区中，并持久化到 ~/.database-mcp/last-queries/，保留时间为 1 小时。

// Example: normal (default) response
{
  "call_id": "k3m9a2xp",
  "columns": ["id", "title", "content"],
  "rows": [
    { "id": 1, "title": "Hello", "content": "<h1>Long HTML…(+1847B)" }
  ],
  "rowCount": 1,
  "executionTimeMs": 12,
  "cells_truncated": 1,
  "hint": "1 cell(s) truncated to 500 bytes. Use inspect_last_query({ call_id: \"k3m9a2xp\" }) for full values.",
  "tokens_saved_estimate": 462
}

原生替代方案：实际令牌成本

当 database 不可用时，此 MCP 与 Claude Code 可用的原生选项（Bash + psql、sqlite3、mysql CLI 等）相比如何。

简而言之：与原始 psql 相比，execute_query 可节省 78% 到 96% 的上下文令牌，具体取决于模式，且不会丢失调试信息。测量方式：在 PostgreSQL 表上实际调用 SELECT * FROM blog_posts LIMIT 5，该表的 content 列每行包含约 1 KB 的 HTML：

此表中的数字与上文“压缩模式”一节不同，原因是：这些数字来自一次包含 5 行的真实查询，而上表是根据包含 100 行、内容更大的结果推算得出。趋势和数量级相同。

注意：

• 随着行数增加，原始 psql 输出会变得更糟——JSONB 和较长的 TEXT 列没有原生筛选功能。MCP 的单元格截断会保留结构（行数 + 列列表），同时用 …(+NB) 标记折叠较大的单元格。
• inspect_last_query 无需重新运行 SQL，即可恢复完整结果。使用 psql 时必须重新执行查询，这会再次消耗数据库 CPU，并可能导致 RETURNING 子句的副作用再次触发。
• MCP 还提供了没有直接原生替代方案的功能：限定于项目目录的连接组、修改操作的自动回滚快照、查询历史记录、通过 MCP 资源进行的架构内省，以及转储/还原。
• 在相关情况下，响应末尾会附加架构上下文（normal/full 默认值为 true）。如果 Agent 已了解架构，可使用 include_schema_context: false 将其禁用。
• 每个已注册的 MCP 每个会话都会增加固定开销，约为 300–600 个令牌（其指令块 + 工具名称）。典型的盈亏平衡点：每个会话执行 1 次实际查询。

转储和还原

以 SQL 格式完整备份数据库——仅包含结构，或同时包含结构和数据。

"Dump the database"
  -> Choose: structure only or full
  -> Choose: all tables or specific ones
  -> SQL file saved to .database-mcp/dumps/

"Restore from the last dump"
  -> Lists available dumps, asks for confirmation, executes

生成的 SQL 会处理 DROP TABLE IF EXISTS、禁用/启用 FK，以及适配方言的 DDL。

查询历史记录

每条查询都会按项目记录时间戳、连接、执行时间和结果类型。

"What queries did I run today?"
"Show me only mutations"
"History for the prod connection"

导出和导入连接

"Export all connections"                    -> JSON with masked passwords
"Export with secrets included"             -> JSON with real credentials
"Import these connections: { ... }"        -> creates missing connections

工具参考

33 个工具分为 8 类，另有 2 个 MCP 资源：

资源： db://schema · db://tables/{tableName}/schema

提示： 你无需直接调用这些工具。只需描述你的需求，AI 就会选择合适的工具。

存储

存储按设计分为两个位置。这种分离是有意为之，旨在解决实际问题：凭据属于你，项目历史记录属于项目。

全局：~/.database-mcp/ — 群组、连接、凭据和设置。位于你的主目录中。从不存放在项目内，也从不提交到 git。除非你明确导出，否则绝不与任何人共享。

按项目：{project}/.database-mcp/ — 查询历史记录、回滚快照和数据库转储。位于项目目录内，并会在首次写入时自动添加到 .gitignore。

~/.database-mcp/                          # Global (configurable via DATABASE_MCP_DIR)
├── groups/                               # Connection groups with scopes and defaults
├── connections/                          # Connection configs (credentials, chmod 600)
├── project-conns.json                    # Session-only active connections (cleared on restart)
└── config.json                           # Server config (limits)

{your-project}/.database-mcp/            # Per-project (auto-gitignored)
├── history.json                          # Query history (max 5000)
├── rollbacks.json                        # Pre-mutation snapshots (max 1000)
└── dumps/
    └── {conn}-{timestamp}-{mode}.sql     # Database dumps

这样一来，你可以自由共享项目仓库——协作者可以获取历史记录和回滚结构，但不会获得任何凭据。他们可以在本地创建自己的连接和群组。

配置

可在对话中配置，也可通过环境变量配置：

"Set max rollbacks to 2000"
"Set max history to 10000"

优先级：环境变量 > 已保存的配置 > 默认值。

警告： 如果将 DATABASE_MCP_DIR 覆盖为 git 仓库内的路径，请将 .database-mcp/ 添加到 .gitignore，以免推送凭据。

架构

src/
├── index.ts              # Entry point (StdioServerTransport)
├── server.ts             # createServer() factory
├── tools/                # 33 tool handlers (one file per category)
├── resources/            # MCP Resources (schema auto-discovery)
├── services/             # Business logic
│   ├── connection-manager    # Lazy connect, driver caching
│   ├── schema-introspector   # Multi-dialect introspection (3 detail levels)
│   ├── query-executor        # Read/mutation/explain with safety
│   ├── rollback-manager      # Snapshot capture + reverse SQL
│   ├── history-logger        # Per-project query log
│   └── dump-manager          # Dump/restore (SQL generation)
├── drivers/              # Database adapters (postgres, mysql, sqlite)
├── lib/                  # Types, storage, sanitization
└── utils/                # SQL classifier, parser, formatter

• 除 @modelcontextprotocol/sdk 和 zod 外，零运行时依赖
• 严格的 TypeScript — 不使用 any
• 动态加载驱动程序 — 在运行时使用 import('postgres') / import('mysql2/promise') / import('sql.js')
• 使用 tsup 打包后 小于 60KB
• 工厂模式 — createServer(storageDir?, projectDir?)，用于创建隔离的测试实例

MIT · 由 cocaxcode 构建