db-view-mcp

db-view-mcp

一款 MCP 服务，可让 AI 助手直接访问 PostgreSQL 和 ClickHouse 数据库。它支持 stdio 和 HTTP 两种传输方式，可用于本地 IDE 集成和远程网络访问。

功能

• 多数据库 — 可同时连接任意数量的 PostgreSQL 和 ClickHouse 实例
• 双传输方式 — stdio 用于 IDE 集成（Cursor、Claude Code），HTTP 用于远程/多客户端访问
• 读写工具 — SELECT（含行数限制）、INSERT/UPDATE/DELETE、DDL、事务
• 架构检查 — 列出表、描述列、导出完整 DDL
• 查询分析 — EXPLAIN / EXPLAIN ANALYZE、慢查询跟踪
• SQL 安全 — 只读工具会验证 SQL 并阻止意外写入
• 灵活的工具模式 — 使用一个带有 database 参数的工具，或为每个数据库单独提供工具
• 延迟连接 — 默认在首次使用时连接数据库
• Bearer 身份验证 — 可选的 HTTP 传输令牌身份验证
• 会话管理 — 有状态模式（每个会话一个 MCP 服务）或无状态 HTTP 模式

安装

npm install @conte777/db-view-mcp

或者克隆并从源代码构建：

git clone <repo-url>
cd db-view-mcp
npm install
npm run build

快速开始

1. 配置

复制示例配置并进行编辑：

cp config.example.json config.json

最简 stdio 配置：

{
  "databases": [
    {
      "id": "main_pg",
      "type": "postgresql",
      "host": "localhost",
      "port": 5432,
      "database": "myapp",
      "user": "admin",
      "password": "secret123"
    }
  ]
}

所有字段、默认值和完整配置参考（SSL/TLS、按数据库覆盖、环境变量替换、HTTP 传输）请参阅 docs/configuration.md。

2. 运行

# Stdio (default)
npm start -- --config config.json

# HTTP (set transport.type to "http" in config, or override on the CLI)
npm start -- --config config.json --transport http

# Development (no build needed)
npm run dev -- --config config.json

3. 添加 MCP 客户端

Claude Desktop（claude_desktop_config.json）或 Claude Code（.mcp.json），stdio：

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@conte777/db-view-mcp", "--config", "/path/to/config.json"]
    }
  }
}

任何 MCP 客户端，HTTP：

node dist/index.js --config config.json --transport http
# Server listens on http://127.0.0.1:3000/mcp

会话、身份验证和 curl 示例请参阅 docs/http-transport.md。

文档

文档	内容
docs/configuration.md	所有配置字段、默认值、SSL/TLS、rowFormat、环境变量替换、热重载
docs/tools.md	9 个工具：参数、输出、示例、错误代码、按数据库模式
docs/http-transport.md	stdio 与 HTTP、会话、Bearer 身份验证、/health、curl
docs/security.md	只读 SQL 验证器、拒绝列表、响应上限、网络暴露
docs/architecture.md	源码树、分层、连接器模型、生命周期（热重载、关闭）
CONTRIBUTING.md	构建、测试、代码检查、钩子、CI

ClickHouse 限制

• 不支持事务（transaction begin 会抛出异常）。
• 查询 params 会被忽略 — 请在 SQL 中使用 ClickHouse 原生的 {name:Type} 语法。

开发

构建/测试/代码检查命令、覆盖率阈值、git 钩子和 CI 的说明请参阅 CONTRIBUTING.md。

许可证

MIT