SQL-MCP

数据库上下文协议（Model Context Protocol, MCP）服务器，提供数据库元数据、样本数据与只读查询能力，支持 stdio 与 Streamable HTTP 传输。

English version below. 如需英文全文，请见 README.en.md。变更记录见 CHANGELOG.md。

---

安装

• 全局安装（推荐）

npm i -g @polarisxb/sql-mcp

• 或源码构建

npm ci
npm run build

快速开始

• 使用 stdio 启动（适合在 Cursor/Claude Desktop 里作为命令型 MCP）

sql-mcp --type mysql \
  --host 127.0.0.1 --port 3306 \
  --user root --password ****** --database mydb \
  --transport stdio

• 使用 HTTP 启动（提供 /mcp 接口，外部通过 URL 连接）

sql-mcp --type mysql \
  --host 127.0.0.1 --port 3306 \
  --user root --password ****** --database mydb \
  --transport http --httpPort 3000

• 日志与输出

sql-mcp --verbose
sql-mcp --log-dest file --log-file ./logs/sql-mcp.log

Cursor 集成

• stdio（推荐）：
  • command: node
  • args: ["C:/all_project/sql-mcp/dist/cli.js", "--transport", "stdio"]
  • Env: 设置 SQL_MCP_* 数据库只读账号
• http：
  • url: http://127.0.0.1:3000/mcp

配置

配置优先级：默认值 < .env/JSON/JS 配置 < 环境变量（SQL_MCP_*）。

常用环境变量（节选）：

• 数据库
  • SQL_MCP_DB_TYPE → database.type（mysql）
  • SQL_MCP_DB_HOST / SQL_MCP_DB_PORT / SQL_MCP_DB_USER / SQL_MCP_DB_PASSWORD / SQL_MCP_DB_NAME
  • SQL_MCP_DB_TIMEOUT（连接超时毫秒）
• 日志
  • SQL_MCP_LOG_LEVEL（debug|info|warn|error）
  • SQL_MCP_LOG_DESTINATION（console|file）
  • SQL_MCP_LOG_FILE_PATH
• MCP
  • SQL_MCP_MCP_TRANSPORT（stdio|http）
  • SQL_MCP_MCP_HTTP_PORT

复制 ENV.example 作为模板并填充。

CLI 选项一览

选项	类型	默认	说明	示例
--type	string	mysql	数据库类型（当前支持 MySQL）	--type mysql
--host	string	127.0.0.1	数据库主机	--host 192.168.1.10
--port	number	3306	数据库端口	--port 3306
--user	string	-	数据库用户（建议只读权限）	--user reader
--password	string	-	数据库密码	--password secret
--database	string	-	默认数据库/Schema	--database appdb
--transport	enum	stdio	MCP 传输：stdio 或 http	--transport http
--httpPort	number	3000	HTTP 服务器端口（当 --transport http 时生效）	--httpPort 3000
--verbose	flag	false	打印 debug 日志	--verbose
--log-dest	enum	console	日志目的地：console/file	--log-dest file
--log-file	string	-	日志文件路径（当 --log-dest file 时生效）	--log-file ./logs/sql-mcp.log

等价环境变量：均可用 SQL_MCP_* 设置，优先级高于文件配置。

环境变量对照表

环境变量	类型/默认	说明
SQL_MCP_DB_TYPE	mysql	数据库类型
SQL_MCP_DB_HOST	127.0.0.1	主机
SQL_MCP_DB_PORT	3306	端口
SQL_MCP_DB_USER	-	用户
SQL_MCP_DB_PASSWORD	-	密码
SQL_MCP_DB_NAME	-	数据库名
SQL_MCP_DB_TIMEOUT	10000	连接超时（ms）
SQL_MCP_DB_POOL_CONNECTION_LIMIT	10	连接池最大连接数
SQL_MCP_DB_POOL_WAIT_FOR_CONNECTIONS	true	池满时是否等待
SQL_MCP_DB_POOL_QUEUE_LIMIT	0	等待队列上限（0=无限）
SQL_MCP_LOG_LEVEL	info	日志级别：`debug
SQL_MCP_LOG_DESTINATION	console	日志目的地：`console
SQL_MCP_LOG_FILE_PATH	-	文件路径（当目的地为 file）
SQL_MCP_LOG_SLOW_QUERY_MS	1000	慢查询阈值（ms），超过则 warn
SQL_MCP_LOG_HTTP_REQUESTS	true	是否记录 HTTP 请求日志
SQL_MCP_MCP_TRANSPORT	stdio	MCP 传输：`stdio
SQL_MCP_MCP_HTTP_PORT	3000	HTTP 端口（当传输为 http）
SQL_MCP_MCP_HTTP_API_KEY	-	单个 API Key（可选）
SQL_MCP_MCP_HTTP_API_KEYS	-	多个 API Key，逗号分隔
SQL_MCP_MCP_ENABLE_DNS_REBINDING_PROTECTION	false	启用 Host 校验
SQL_MCP_MCP_ALLOWED_HOSTS	-	允许的 Host 列表，逗号分隔
SQL_MCP_MCP_CORS_ALLOWED_ORIGINS	-	允许的 CORS Origin 列表，逗号分隔
SQL_MCP_SECURITY_SAMPLE_MAX_ROWS	100	采样最大行数上限
SQL_MCP_SECURITY_QUERY_TIMEOUT_MS	10000	查询超时时间（ms）
SQL_MCP_SECURITY_RATE_LIMIT_ENABLED	false	启用 /mcp 路由限流
SQL_MCP_SECURITY_RATE_LIMIT_WINDOW_MS	60000	限流窗口（ms）
SQL_MCP_SECURITY_RATE_LIMIT_MAX	120	窗口内全局最大请求数
SQL_MCP_SECURITY_RATE_LIMIT_PER_IP_MAX	60	窗口内单 IP 最大请求数

更多映射详见 src/core/config/loader.ts。

功能概览

• 元数据：库/表/列、索引、约束、关系
• 取样：SELECT * FROM schema.table LIMIT N（WHERE 可选，自动脱敏）；当存在更多数据时，返回中包含 hasMore=true，可用 offset+limit 作为下一页起点。
• 查询：只读（SELECT/SHOW