Provides read-only database access with capabilities for retrieving database metadata, sample data, and executing secure queries against MySQL databases
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):
返回说明:上述工具均以 text + resource(application/json)
形式返回;证据 JSON 中包含执行计划/分析/建议/改写等结构化信息,便于二次处理或验证。
🚀 快速开始
1. 安装
您可以选择通过 npm
全局安装,或从源码克隆后构建。
全局安装 (推荐):
从源码构建:
2. 启动服务
根据您的使用场景,选择合适的启动方式。
通过 Stdio (标准输入/输出):
此方式适合在 Cursor 或其他支持命令式 MCP 的工具中进行本地集成。
通过 HTTP:
将 SQL-MCP 作为独立的 HTTP 服务运行,供远程应用调用。
服务将在 http://127.0.0.1:3000/mcp
提供 API 端点。
3. Demo 快速体验(MySQL + 示例电商库)
说明:
mysql:8
暴露 3306,sql-mcp
暴露为http://127.0.0.1:3001/mcp
。如端口被占用,可在
docker-compose.yml
中调整端口映射。
4. 使用 DSN 启动(本地 CLI)
5. MCP 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 (无需全局安装):
从源码运行 (供开发者):
如果您想使用开发中的版本,可以配置从项目目录启动。
HTTP 模式
如果您已将 SQL-MCP 作为独立的 HTTP 服务运行,可以在 Cursor 中通过 URL 连接。
⚙️ 配置选项
SQL-MCP 支持通过命令行参数、环境变量和配置文件进行配置。
配置优先级: 命令行参数 > 环境变量 > 配置文件。
命令行参数
以下为常用的命令行参数:
选项 | 类型 | 默认 | 说明 |
| string |
| 数据库类型 (当前仅支持
) |
| string |
| 数据库主机 |
| number |
| 数据库端口 |
| string | - | 数据库用户名 (建议使用只读权限) |
| string | - | 数据库密码 |
| string | - | 默认数据库 |
| enum |
| 传输模式 (
或
) |
| number |
| HTTP 服务的端口 |
| flag |
| 输出详细的
日志 |
| enum |
| 日志输出位置 (
或
) |
| string | - | 日志文件路径 (当
为
时) |
| flag |
| Stdio 安全预设:优化日志,精简输出 |
| flag |
| 紧凑输出,减少 Markdown 体积 |
| flag |
| 仅输出 JSON 内容,无 Markdown 渲染 |
环境变量
所有配置项都可以通过前缀为 SQL_MCP_
的环境变量进行设置。例如, --host
对应的环境变量为 SQL_MCP_DB_HOST
。
复制 ENV.example
文件为 .env
并填入您的数据库连接信息,是快速开始的好方法。
环境变量对照表
环境变量 | 默认值 | 说明 |
数据库连接 | ||
|
| 数据库类型 |
|
| 主机 |
|
| 端口 |
| - | 用户 |
| - | 密码 |
| - | 数据库名 |
|
| 连接超时 (ms) |
|
| 连接池最大连接数 |
|
| 等待队列上限 (
=无限) |
日志 | ||
|
| 日志级别:
|
|
| 日志目的地:
|
| - | 文件路径 (当目的地为
) |
|
| 慢查询阈值 (ms) |
|
| 是否记录 HTTP 请求日志 |
服务与安全 | ||
|
| MCP 传输:
|
|
| HTTP 端口 |
| - | 单个 API Key |
| - | 多个 API Key,逗号分隔 |
|
| 启用 Host 校验 |
| - | 允许的 CORS Origin,逗号分隔 |
|
| 查询超时时间 (ms) |
|
| 采样最大行数上限 |
|
|
单次返回行数上限 |
|
| 启用
路由限流 |
|
| 限流窗口 (ms) |
|
| 窗口内全局最大请求数 |
|
| 窗口内单 IP 最大请求数 |
其他 | ||
|
| 启动时后台预热表清单 |
|
| 启用 stdio 安全预设 |
|
| 启用紧凑输出 |
|
| 仅输出 JSON 内容 |
更多配置细节请参阅
src/core/config/loader.ts
。
🏛️ 项目结构
🤝 贡献
我们非常欢迎社区通过 Pull Request 或 Issues 为项目做出贡献。在提交代码前,请确保您的代码通过了 lint 和 test 检查。
📄 开源许可
本项目基于 MIT 许可开源。
This server cannot be installed
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
- -securityAlicense-qualityAn 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 -8717MIT License
- AsecurityAlicenseAqualityAn MCP server that provides read-only access to MySQL databases.Last updated -428843MIT License
- -securityFlicense-qualityAn 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 -3114
- -securityFlicense-qualityProvides MySQL database integration for AI assistants and other MCP clients, allowing them to list tables, read table data, and execute SQL queries.Last updated -