@edwardchu/mcp-database

只读 MCP 数据库探索服务，支持 PostgreSQL · MySQL · SQLite · 达梦(DM) 四种数据库。

通过 MCP（Model Context Protocol）协议暴露 8 个数据库探索工具，让 AI 助手能安全地查询表结构、执行只读 SQL、分析执行计划。所有操作均为只读 — 写操作在 SQL 策略层即被拦截，杜绝误操作风险。

特性

• 🔒 只读安全 — SQL 策略引擎拦截所有写操作（INSERT/UPDATE/DELETE/DROP/TRUNCATE…），只允许 SELECT/WITH
• 🗄️ 多数据库支持 — 一套代码四种方言，通过连接串自动识别
• ⏱️ 超时保护 — 查询、EXPLAIN、闲置事务均有独立超时，防止慢查询阻塞
• 📦 零配置启动 — 只需一个 DATABASE_URL，自动推断数据库类型
• 🏷️ 多实例并行 — 一个 .mcp.json 可注册多个数据库实例，AI 通过实例名区分

环境要求

• Node.js >= 18.0.0
• 数据库账号建议只读权限（本服务自身也做了只读防护，但最小权限原则更安全）

快速开始

方式一：npx 直接运行（推荐，无需安装）

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "my-db": {
      "command": "npx",
      "args": ["-y", "@edwardchu/mcp-database"],
      "env": {
        "DATABASE_URL": "postgres://user:password@host:5432/dbname"
      }
    }
  }
}

方式二：全局安装

npm install -g @edwardchu/mcp-database

然后在 .mcp.json 中使用 mcp-database 命令：

{
  "mcpServers": {
    "my-db": {
      "command": "mcp-database",
      "env": {
        "DATABASE_URL": "postgres://user:password@host:5432/dbname"
      }
    }
  }
}

方式三：项目内安装

npm install @edwardchu/mcp-database

{
  "mcpServers": {
    "my-db": {
      "command": "npx",
      "args": ["@edwardchu/mcp-database"],
      "env": {
        "DATABASE_URL": "postgres://user:password@host:5432/dbname"
      }
    }
  }
}

支持的数据库

| 数据库 | 连接串 scheme | 示例 | |--------|--------------|------| | PostgreSQL | postgres:// 或 postgresql:// | postgres://user:pass@host:5432/db | | MySQL | mysql:// | mysql://user:pass@host:3306/db | | SQLite | sqlite:// 或 file: | sqlite:///path/to/db.sqlite | | 达梦 (DM) | dm:// | dm://SYSDBA:SYSDBA@host:5236 |

也可用 DB_TYPE 环境变量显式指定方言：postgres | mysql | sqlite | dameng（覆盖 URL scheme 自动推断）

多数据库配置

一个 .mcp.json 中可注册多个数据库实例，每个实例独立运行：

{
  "mcpServers": {
    "pg-incident": {
      "command": "npx",
      "args": ["-y", "@edwardchu/mcp-database"],
      "env": {
        "DATABASE_URL": "postgres://postgres:password@IP:端口/db1"
      }
    },
    "mysql-wvp": {
      "command": "npx",
      "args": ["-y", "@edwardchu/mcp-database"],
      "env": {
        "DATABASE_URL": "mysql://root:password@IP:端口/db2"
      }
    },
    "dm-production": {IP:端口
      "command": "npx",
      "args": ["-y", "@edwardchu/mcp-database"],
      "env": {
        "DATABASE_URL": "dm://SYSDBA:password@IP:端口IP:端口"
      }
    }
  }
}

AI 助手会看到所有已注册的数据库实例，并通过实例名（如 pg-incident、mysql-wvp）区分调用。

可用工具

| 工具 | 说明 | |------|------| | query | 执行只读 SQL（仅 SELECT / WITH） | | explain_query | 分析 SQL 执行计划 | | list_schemas | 列出所有用户 Schema | | list_tables | 列出指定 Schema 下的表和视图 | | list_relations | 同 list_tables（别名） | | describe_table | 查看表/视图的列定义 | | list_indexes | 查看表的索引 | | list_constraints | 查看表的约束（PK / FK / UNIQUE） |

环境变量

通用：

| 变量 | 说明 | 默认值 | |------|------|--------| | DATABASE_URL | 数据库连接串 | — | | DB_TYPE | 显式指定方言（覆盖 URL scheme 推断） | 自动检测 |

各方言查询限制（独立前缀）：

| 配置项 | PG 前缀 | MySQL 前缀 | SQLite 前缀 | DM 前缀 | 默认值 | |--------|---------|-----------|------------|---------|--------| | 最大返回行数 | PG_MCP_MAX_ROWS | MYSQL_MCP_MAX_ROWS | SQLITE_MCP_MAX_ROWS | DM_MCP_MAX_ROWS | 100 | | 查询超时 (ms) | PG_MCP_STATEMENT_TIMEOUT_MS | MYSQL_MCP_STATEMENT_TIMEOUT_MS | SQLITE_MCP_STATEMENT_TIMEOUT_MS | DM_MCP_STATEMENT_TIMEOUT_MS | 5000 | | EXPLAIN 超时 (ms) | PG_MCP_EXPLAIN_TIMEOUT_MS | MYSQL_MCP_EXPLAIN_TIMEOUT_MS | SQLITE_MCP_EXPLAIN_TIMEOUT_MS | DM_MCP_EXPLAIN_TIMEOUT_MS | 3000 | | 闲置事务超时 (ms) | PG_MCP_IDLE_TX_TIMEOUT_MS | MYSQL_MCP_IDLE_TX_TIMEOUT_MS | SQLITE_MCP_IDLE_TX_TIMEOUT_MS | DM_MCP_IDLE_TX_TIMEOUT_MS | 5000 | | 最大响应体 (bytes) | PG_MCP_MAX_RESPONSE_BYTES | MYSQL_MCP_MAX_RESPONSE_BYTES | SQLITE_MCP_MAX_RESPONSE_BYTES | DM_MCP_MAX_RESPONSE_BYTES | 524288 |

示例 — 调整 PostgreSQL 查询限制：

{
  "mcpServers": {
    "my-pg": {
      "command": "npx",
      "args": ["-y", "@edwardchu/mcp-database"],
      "env": {
        "DATABASE_URL": "postgres://user:pass@host:5432/db",
        "PG_MCP_MAX_ROWS": "500",
        "PG_MCP_STATEMENT_TIMEOUT_MS": "10000"
      }
    }
  }
}

安全机制

• 只读事务 — 所有查询在只读事务中执行，数据库层面双重保险
• SQL 策略拦截 — 禁止 INSERT/UPDATE/DELETE/DROP/TRUNCATE 等写关键字
• 单语句限制 — 拒绝分号分隔的多语句注入
• 行数上限 — 查询结果自动 LIMIT，防止超大结果集
• 超时保护 — 防止慢查询阻塞连接
• 响应体限制 — 防止超大结果集撑爆 MCP 通道

连接串格式

PostgreSQL:  postgres://user:password@host:port/database
MySQL:       mysql://user:password@host:port/database
达梦 (DM):   dm://user:password@host:port
SQLite:      sqlite:///absolute/path/to/db.sqlite
             sqlite://relative/path.db
             :memory:

常见问题

| 问题 | 解决方案 | |------|----------| | 达梦连接报 error:0308010C:digital envelope routines::unsupported | 程序已自动注入 --openssl-legacy-provider，若仍失败请检查 Node.js 版本 >= 18 | | PostgreSQL 不设 DATABASE_URL | 自动读取 PGHOST/PGPORT/PGUSER/PGPASSWORD/PGDATABASE 环境变量 | | MySQL information_schema 列名大小写 | 已内部处理，无需关注 | | 达梦连接不需要指定数据库名 | 达梦一个实例即一个数据库，数据隔离靠 Schema | | SQLite 报 Could not locate the bindings file | 需编译原生模块：npm rebuild better-sqlite3（依赖系统编译工具） |

License

MIT