every-database-mcp

一个支持多种数据库的 MCP (Model Context Protocol) Server，让 AI 助手能够安全地查询和探索你的数据库。

特性

• 多数据库支持 — 首批支持 MySQL、SQLite、Oracle，架构设计上易于扩展新的数据库类型
• 安全优先 — 默认只允许 SELECT 查询，写操作需要在配置中显式开放
• 操作白名单 — 每个连接可独立配置允许的操作类型（select / insert / update / delete / ddl / transaction）
• 强制分页 — SELECT 查询自动注入分页，防止海量数据溢出（默认 100 条/页，硬上限 1000 条）
• 多连接管理 — 单实例同时管理多个数据库连接
• 三种传输模式 — 支持 stdio（本地 IDE）、Streamable HTTP（远程/共享，现行标准）和 SSE（旧客户端兼容）
• 环境变量替换 — 配置文件中密码等敏感字段支持 ${ENV_VAR} 语法

环境要求

• Node.js >= 18（推荐 20 LTS 或更高）

快速开始

安装

npm install -g every-database-mcp

或使用 npx 直接运行（无需全局安装）：

npx every-database-mcp --config ./every-db-mcp.yaml

配置

复制示例配置文件并根据实际情况修改：

cp every-db-mcp.example.yaml every-db-mcp.yaml

最小化配置示例：

connections:
  - name: my-db
    type: mysql
    host: localhost
    port: 3306
    user: root
    password: ${MYSQL_PASSWORD}
    database: myapp

配置文件查找顺序：

1. --config 参数指定的路径
2. 当前工作目录下的 every-db-mcp.yaml
3. ~/.every-db-mcp/config.yaml

在 Cursor / Claude Desktop 中使用

在 MCP 配置中添加：

{
  "mcpServers": {
    "every-database-mcp": {
      "command": "npx",
      "args": ["every-database-mcp", "--config", "/path/to/every-db-mcp.yaml"]
    }
  }
}

以 HTTP 模式运行（推荐远程方式）

every-database-mcp --transport http --port 3000 --config ./every-db-mcp.yaml

成功启动时应看到 every-database-mcp v1.1.1 starting (transport=http, port=3000)，以及 Streamable HTTP: http://localhost:3000/mcp。若日志是 MCP server running on stdio，说明用到了不含 HTTP 传输的旧构建（npm 上的 1.1.0 仍是旧逻辑），请使用 npx [email protected] 或从本仓库 npm run build 后运行。

--transport http、streamable-http 和 sse 会启动同一个 HTTP 服务，同时提供：

• POST/GET/DELETE /mcp — Streamable HTTP（Cursor / VS Code / Claude Code 等新客户端）
• GET /sse + POST /messages — 旧版 SSE（兼容已有配置）

局域网共享访问（典型场景）

当数据库部署在内网服务器上（如 Oracle），你希望局域网内多台电脑的 AI 助手都能查询它：

1. 在数据库所在服务器（或同网段机器）上部署 MCP server：

# 在服务器上创建配置文件 every-db-mcp.yaml
# 然后以 HTTP 模式启动，监听所有网卡
npx every-database-mcp --transport http --port 3000 --config ./every-db-mcp.yaml

配置示例（以 Oracle 为例）：

connections:
  - name: oracle-prod
    type: oracle
    host: localhost          # 服务器本地连接，无需走网络
    port: 1521
    user: YOUR_USER
    password: ${ORACLE_PASSWORD}
    serviceName: XEPDB1

2. 局域网内其他电脑在 Cursor 中配置 HTTP 连接：

假设服务器 IP 为 192.168.1.100：

{
  "mcpServers": {
    "oracle-db": {
      "url": "http://192.168.1.100:3000/mcp"
    }
  }
}

这样只需在服务器上配置一次，局域网内所有客户端零安装、零配置即可使用。

旧客户端若仍使用 "url": "http://192.168.1.100:3000/sse"，无需改服务端，同一进程继续提供 SSE。

服务器端后台常驻

如果需要在服务器上长期运行，推荐使用 pm2 管理进程：

npm install -g pm2
pm2 start npx -- every-database-mcp --transport http --port 3000 --config ./every-db-mcp.yaml
pm2 save

也可以用 nohup 简单后台运行：

nohup npx every-database-mcp --transport http --port 3000 --config ./every-db-mcp.yaml &

配置详解

完整配置结构

connections:
  # MySQL 连接
  - name: my-mysql            # 连接名称（唯一标识）
    type: mysql
    host: localhost
    port: 3306
    user: root
    password: ${MYSQL_PASSWORD} # 支持环境变量替换
    database: myapp
    allowedOperations:          # 允许的操作类型
      - select                  # 默认仅开启 select
      # - insert
      # - update
      # - delete
      # - ddl                   # CREATE / ALTER / DROP
      # - transaction           # BEGIN / COMMIT / ROLLBACK
    pool:
      min: 1
      max: 5

  # SQLite 连接
  - name: my-sqlite
    type: sqlite
    filepath: ./data/local.db   # SQLite 文件路径

  # Oracle 连接
  - name: my-oracle
    type: oracle
    host: localhost
    port: 1521
    user: SYSTEM
    password: ${ORACLE_PASSWORD}
    serviceName: XEPDB1         # 或使用 connectString 直接指定

pagination:
  defaultPageSize: 100          # 默认每页行数
  maxPageSize: 1000             # 硬上限（不可超越）

logLevel: info                  # debug | info | warn | error

环境变量替换

配置文件中任何字符串值都可以使用 ${ENV_VAR} 引用环境变量：

password: ${DB_PASSWORD}
host: ${DB_HOST}

如果密码以明文写在配置文件中，启动时会输出警告提示。

可用 Tools

| Tool | 说明 | 参数 | |------|------|------| | list_connections | 列出所有已配置的数据库连接及状态 | 无 | | list_schemas | 列出连接下的所有 schema/数据库 | connection | | list_tables | 列出指定 schema 下的所有表和视图 | connection, schema? | | describe_table | 查看表的列定义（列名、类型、主键、注释等） | connection, table, schema? | | get_table_ddl | 获取表的 CREATE TABLE 建表语句 | connection, table, schema? | | query | 执行 SELECT 查询（强制分页，仅允许 SELECT） | connection, sql, page?, pageSize?, format? | | execute | 执行非 SELECT 语句（受白名单管控） | connection, sql |

query 参数说明

• page — 页码，从 1 开始，默认 1
• pageSize — 每页行数，默认取配置的 defaultPageSize，不能超过 maxPageSize
• format — 返回格式：json（默认）或 markdown（Markdown 表格）

execute 安全机制

execute 会通过 SQL Parser 解析语句类型，与该连接的 allowedOperations 白名单进行匹配。未授权的操作会被拒绝并返回错误信息。

CLI 参数

Usage: every-database-mcp [options]

Options:
  -c, --config <path>      配置文件路径
  -t, --transport <type>   传输方式：stdio（默认）、http / streamable-http、或 sse
  -p, --port <number>      HTTP 模式端口号（默认 3000）
  --log-level <level>      日志级别：debug / info / warn / error
  -V, --version            显示版本号
  -h, --help               显示帮助

扩展新数据库

1. 在 src/adapters/ 下创建新的适配器类，继承 DatabaseAdapter 抽象类
2. 实现所有抽象方法（connect, listSchemas, listTables, describeTable, getTableDDL, executeQuery, executeStatement 等）
3. 在 src/adapters/index.ts 的 ADAPTER_MAP 中注册新类型
4. 在 src/types.ts 的 DatabaseType 联合类型中添加新类型

本地开发

# 安装依赖
npm install

# 编译
npm run build

# 监听模式编译
npm run dev

# 运行
npm start -- --config ./every-db-mcp.yaml

发布到 npm

# 1. 登录 npm 官方源（系统会自动要求 2FA 验证）
npm login --registry https://registry.npmjs.org/

# 2. 构建
npm run build

# 3. 发布（指定官方源，避免发到镜像）
npm publish --registry https://registry.npmjs.org/

如需发布为 scoped 包（如 @yourorg/every-database-mcp），修改 package.json 中的 name 字段后：

npm publish --access public

发布后用户即可通过 npx every-database-mcp 直接运行。

License

MIT