SQL MCP Server

SQL-MCP

SQL-MCP 是一个实现了模型上下文协议 (Model Context Protocol, MCP) 的服务器，其核心功能是作为连接大型语言模型 (LLM) 与数据库的桥梁。它允许 LLM 安全、高效地访问数据库信息，包括进行元数据查询、数据采样和只读SQL查询。

本项目当前主要支持 MySQL，并提供 Stdio 和 HTTP 两种灵活的传输方式，既可以作为独立的 HTTP 服务运行，也可以轻松集成到其他开发工具链中。

如需英文版本，请参阅 README.en.md。

✨ 功能特性

元数据查询: 详细查询数据库、表、列、索引、外键等元信息。
数据采样: 安全地获取表的示例数据，支持分页和自动脱敏。
只读查询: 严格限制执行 SELECT 和 SHOW 等只读 SQL，保障数据安全。
快速检索: 提供 searchTables 和 searchColumns 接口，用于快速查找表和列。
缓存管理: 支持手动刷新元数据缓存，确保大模型获取的信息实时准确。
安全可靠: 内置 API Key 认证、CORS 控制、IP 限流等多重安全机制。

SQL 导师工具（新）

explainQuery(sql): 解释查询涉及的表/连接/过滤/排序，并提示潜在风险。
optimizeQuery(sql): 给出启发式优化建议（索引/改写/SELECT 列裁剪等）。
generateExamples(tableName): 按表生成常见示例查询与简要讲解。
fixQuery(sql, error): 基于错误信息提供只读等价写法或修复建议。
indexAdvisor(sql): 专注索引建议（过滤/连接/排序/冗余）与证据 JSON。
rewriteQuery(sql): 只读等价改写草案（例如 Keyset 分页模板、避免 SELECT*、避免前导通配符）。
doctor(): 系统自检（连通性、只读查询、EXPLAIN 可用性、重复/冗余索引统计）。

示例参数（在 MCP Inspector 中选择对应工具并填入 params）:

// explainQuery
{ "sql": "SELECT p.id, p.name FROM products p JOIN categories c ON p.category_id=c.id WHERE price>50 ORDER BY p.id LIMIT 5" }

// optimizeQuery
{ "sql": "SELECT * FROM orders WHERE order_date >= NOW() - INTERVAL 7 DAY ORDER BY id LIMIT 20" }

// indexAdvisor
{ "sql": "SELECT p.id FROM products p JOIN categories c ON p.category_id=c.id WHERE p.price>50 ORDER BY p.id LIMIT 5" }

// rewriteQuery
{ "sql": "SELECT id FROM orders ORDER BY id LIMIT 20 OFFSET 100" }

// fixQuery
{ "sql": "SELECT x FROM products", "error": "Unknown column 'x' in 'field list'" }

// doctor（无需参数）
{}

返回说明：上述工具均以 text + resource(application/json) 形式返回；证据 JSON 中包含执行计划/分析/建议/改写等结构化信息，便于二次处理或验证��

🚀 快速开始

1. 安装

您可以选择通过 npm 全局安装，或从源码克隆后构建。

全局安装 (推荐):

npm i -g @polarisxb/sql-mcp

从源码构建:

git clone https://github.com/polarisxb/sql-mcp.git
cd sql-mcp
npm ci
npm run build

2. 启动服务

根据您的使用场景，选择合适的启动方式。

通过 Stdio (标准输入/输出):

此方式适合在 Cursor 或其他支持命令式 MCP 的工具中进行本地集成。

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

通过 HTTP:

将 SQL-MCP 作为独立的 HTTP 服务运行，供远程应用调用。

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

服务将在 http://127.0.0.1:3000/mcp 提供 API 端点。

3. Demo 快速体验（MySQL + 示例电商库）

# 启动（首次会自动初始化示例库 mydb）
docker compose up -d

# 健康检查（应返回 200）
curl -i http://127.0.0.1:3001/health

说明：mysql:8 暴露 3306，sql-mcp 暴露为 http://127.0.0.1:3001/mcp。
如端口被占用，可在 docker-compose.yml 中调整端口映射。

4. 使用 DSN 启动（本地 CLI）

# 本地构建版（支持 --dsn）
npm run build
node dist/cli.js --transport stdio --dsn "mysql://root:root@127.0.0.1:3306/mydb"

# 已发布包（npx，不支持 --dsn，用显式参数）
npx -y @polarisxb/sql-mcp --transport stdio \
  --type mysql --host 127.0.0.1 --port 3306 \
  --user root --password root --database mydb

5. MCP Inspector 调试

npx -y @modelcontextprotocol/inspector

连接 HTTP：选择 “Connect to HTTP server”，填 http://127.0.0.1:3001/mcp
启动本地进程（stdio）：选择 “Launch a process”，填写命令和参数（同上）
常用工具：listTables、getTableSchema、getSampleData、executeQuery、searchTables、searchColumns

🔌 Cursor 集成

在 Cursor 中，通过配置 mcp.json 文件即可轻松集成 SQL-MCP。

配置文件路径:

Windows: %USERPROFILE%\\.cursor\\mcp.json
macOS/Linux: ~/.cursor/mcp.json

Stdio 模式 (推荐)

这是最简单直接的集成方式，无需手动启动服务。

使用 npx (无需全局安装):

{
  "mcpServers": {
    "sql-mcp-server": {
      "command": "npx",
      "args": ["-y", "@polarisxb/sql-mcp"],
      "env": {
        "SQL_MCP_DB_TYPE": "mysql",
        "SQL_MCP_DB_HOST": "127.0.0.1",
        "SQL_MCP_DB_PORT": "3306",
        "SQL_MCP_DB_USER": "root",
        "SQL_MCP_DB_PASSWORD": "your_password",
        "SQL_MCP_DB_NAME": "your_database",
        "SQL_MCP_LOG_LEVEL": "warn"
      }
    }
  }
}

从源码运行 (供开发者):

如果您想使用开发中的版本，可以配置从项目目录启动。

{
  "mcpServers": {
    "sql-mcp-dev": {
      "command": "node",
      "args": [
        "C:/path/to/your/sql-mcp/dist/cli.js", 
        "--transport", "stdio"
      ],
      "env": {
        "SQL_MCP_DB_HOST": "127.0.0.1"
      }
    }
  }
}

HTTP 模式

如果您已将 SQL-MCP 作为独立的 HTTP 服务运行，可以在 Cursor 中通过 URL 连接。

{
  "mcpServers": {
    "sql-mcp-http": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

⚙️ 配置选项

SQL-MCP 支持通过命令行参数、环境变量和配置文件进行配置。

配置优先级: 命令行参数 > 环境变量 > 配置文件。

命令行参数

以下为常用的命令行参数：

选项	类型	默认	说明
`--type`	string	`mysql`	数据库类型 (当前仅支持 `mysql`)
`--host`	string	`127.0.0.1`	数据库主机
`--port`	number	`3306`	数据库端口
`--user`	string	-	数据库用户名 (建议使用只读权限)
`--password`	string	-	数据库密码
`--database`	string	-	默认数据库
`--transport`	enum	`stdio`	传输模式 (`stdio` 或 `http`)
`--httpPort`	number	`3000`	HTTP 服务的端口
`--verbose`	flag	`false`	输出详细的 `debug` 日志
`--log-dest`	enum	`console`	日志输出位置 (`console` 或 `file`)
`--log-file`	string	-	日志文件路径 (当 `log-dest` 为 `file` 时)
`--stdio-safe`	flag	`false`	Stdio 安全预设：优化日志，精简输出
`--compact`	flag	`false`	紧凑输出，减少 Markdown 体积
`--json-only`	flag	`false`	仅输出 JSON 内容，无 Markdown 渲染

环境变量

所有配置项都可以通过前缀为 SQL_MCP_ 的环境变量进行设置。例如, --host 对应的环境变量为 SQL_MCP_DB_HOST。

复制 ENV.example 文件为 .env 并填入您的数据库连接信息，是快速开始的好方法。

环境变量对照表

环境变量	默认值	说明
数据库连接
`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_QUEUE_LIMIT`	`0`	等待队列上限 (`0`=无限)
日志
`SQL_MCP_LOG_LEVEL`	`info`	日志级别: `debug\|info\|warn\|error`
`SQL_MCP_LOG_DESTINATION`	`console`	日志目的地: `console\|file`
`SQL_MCP_LOG_FILE_PATH`	-	文件路径 (当目的地为 `file`)
`SQL_MCP_LOG_SLOW_QUERY_MS`	`1000`	慢查询阈值 (ms)
`SQL_MCP_LOG_HTTP_REQUESTS`	`true`	是否记录 HTTP 请求日志
服务与安全
`SQL_MCP_MCP_TRANSPORT`	`stdio`	MCP 传输: `stdio\|http`
`SQL_MCP_MCP_HTTP_PORT`	`3000`	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_CORS_ALLOWED_ORIGINS`	-	允许的 CORS Origin，逗号分隔
`SQL_MCP_SECURITY_QUERY_TIMEOUT_MS`	`10000`	查询超时时间 (ms)
`SQL_MCP_SECURITY_SAMPLE_MAX_ROWS`	`100`	采样最大行数上限
`SQL_MCP_SECURITY_QUERY_MAX_ROWS`	`200`	`executeQuery` 单次返回行数上限
`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 最大请求数
其他
`SQL_MCP_CACHE_PREWARM_ON_START`	`true`	启动时后台预热表清单
`SQL_MCP_MCP_STDIO_SAFE`	`false`	启用 stdio 安全预设
`SQL_MCP_MCP_STDIO_COMPACT`	`false`	启用紧凑输出
`SQL_MCP_OUTPUT_JSON_ONLY`	`false`	仅输出 JSON 内容

更多配置细节请参阅 src/core/config/loader.ts。

🏛️ 项目结构

.
├── src/
│   ├── cli/          # 命令行接口 (CLI) 相关逻辑
│   ├── connectors/   # 数据库连接器 (目前为 MySQL)
│   ├── core/         # 核心业务逻辑，包括配置加载和日志
│   ├── mcp/          # MCP 协议实现和处理器
│   ├── middleware/   # Express 中间件 (认证、日志、限流等)
│   ├── services/     # 核心服务 (元数据、查询、缓存等)
│   ├── types/        # TypeScript 类型定义
│   ├── utils/        # 通用工具函数
│   ├── cli.ts        # CLI 入口文件
│   └── index.ts      # HTTP 服务入口文件
├── Dockerfile        # 用于构建 Docker 镜像
├── package.json      # 项目依赖和脚本
└── tsconfig.json     # TypeScript 配置文件

🤝 贡献

我们非常欢迎社区通过 Pull Request 或 Issues 为项目做出贡献。在提交代码前，请确保您的代码通过了 lint 和 test 检查。

# 代码风格检查
npm run lint

# 运行单元测试
npm run test

📄 开源许可

本项目基于 MIT 许可开源。

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables read-only interaction with SQL databases through MCP, providing database metadata exploration, sample data retrieval, and secure query execution. Supports MySQL with multiple transport options and built-in security features including SQL injection protection and data sanitization.

Related MCP Servers

MySQL MCP Server
kevinwatt
-
security
A
license
-
quality
An MCP server that integrates with MySQL databases, enabling secure read and write operations through LLM-driven interfaces with support for transaction handling and performance monitoring.
Last updated -
390
16
MIT License
MySQL Database Access
dpflucas
A
security
A
license
A
quality
An MCP server that provides read-only access to MySQL databases.
Last updated -
4
257
42
MIT License
MySQL MCP Server
vitalyDV
-
security
F
license
-
quality
An MCP server that allows working with MySQL databases by providing tools for executing read-only SQL queries, getting table schemas, and listing database tables.
Last updated -
596
2
MySQL MCP Server
slg1119
-
security
F
license
-
quality
Provides MySQL database integration for AI assistants and other MCP clients, allowing them to list tables, read table data, and execute SQL queries.
Last updated -

View all related MCP servers

SQL MCP Server

SQL-MCP

✨ 功能特性

SQL 导师工具（新）

🚀 快速开始

1. 安装

2. 启动服务

3. Demo 快速体验（MySQL + 示例电商库）

4. 使用 DSN 启动（本地 CLI）

5. MCP Inspector 调试

🔌 Cursor 集成

Stdio 模式 (推荐)

HTTP 模式

⚙️ 配置选项

命令行参数

环境变量

环境变量对照表

🏛️ 项目结构

🤝 贡献

📄 开源许可

Related MCP Servers

MySQL MCP Server

MySQL Database Access

MySQL MCP Server

MySQL MCP Server

New MCP Servers

MCP directory API