Provides read-only database access with capabilities for retrieving database metadata, sample data, and executing secure queries against MySQL databases
SQL-MCP
数据库上下文协议(MCP)服务器,提供数据库元数据、样本数据与只读查询能力,支持 stdio 与 Streamable HTTP 传输。
安装
快速开始
- 使用 stdio 启动:
- 使用 HTTP 启动:
- 带日志控制:
配置
应用从如下位置加载配置(后者覆盖前者):
- 内置默认值(见
src/core/config/defaults.ts
) - 环境变量(前缀
SQL_MCP_
) - 配置文件(
.env
/.json
/.js
),通过CONFIG_FILE
指定
可复制 ENV.example
作为模板并填入生产环境变量。
环境变量映射(节选):
- 数据库:
SQL_MCP_DB_TYPE
→database.type
(mysql
)SQL_MCP_DB_HOST
→database.host
SQL_MCP_DB_PORT
→database.port
SQL_MCP_DB_USER
→database.user
SQL_MCP_DB_PASSWORD
→database.password
SQL_MCP_DB_NAME
→database.database
SQL_MCP_DB_TIMEOUT
→database.connectionTimeout
- 日志:
SQL_MCP_LOG_LEVEL
→logging.level
(debug|info|warn|error
)SQL_MCP_LOG_DESTINATION
→logging.destination
(console|file
)SQL_MCP_LOG_FILE_PATH
→logging.filePath
- MCP:
SQL_MCP_MCP_TRANSPORT
→mcp.transport
(stdio|http
)SQL_MCP_MCP_HTTP_PORT
→mcp.httpPort
更多映射详见 src/core/config/loader.ts
。
MCP Inspector
建议使用 MCP Inspector 进行调试与测试。
- stdio:选择本地命令,指向
node dist/cli.js ... --transport stdio
- http:配置
POST /mcp
地址,首次初始化后会返回Mcp-Session-Id
并复用
安全
- 所有查询为只读,服务层与处理器对 SQL/WHERE 做注入校验。
- 输出统一脱敏(敏感字段如
password
/token
等会被***
处理)。 - 可选凭证保护:见
src/utils/security.ts
中CredentialManager
。
日志
- 使用
src/utils/logging.ts
,支持级别、彩色控制台、文件输出、子作用域。 - 通过 CLI
--verbose/--log-dest/--log-file
或环境变量控制。
部署
npm 发布
- 打 tag(例如
v1.0.0
)推送后,Release (npm)
工作流会构建、测试并发布到 npm。 - 需要在仓库设置
NPM_TOKEN
(Actions secrets)。
Docker 镜像(GHCR)
- Push 到
main
或推 tag,会由Docker (GHCR)
工作流构建并推送镜像到ghcr.io/polarisxb/sql-mcp
。 - 运行示例:
Compose
docker-compose.yml
已提供(MySQL + 服务),直接docker-compose up -d
。
开发
- 测试:
- 构建:
目录
src/connectors/mysql
:MySQL 连接器与元数据映射/SQL 构建src/services/*
:元数据/采样/安全服务src/mcp/*
:MCP 定义、处理器、服务器工厂、传输src/utils/*
:日志、错误、通用安全工具
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 -75114JavaScriptMIT License
- AsecurityAlicenseAqualityAn MCP server that provides read-only access to MySQL databases.Last updated -491341JavaScriptMIT 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 -6002JavaScript
- -securityAlicense-qualityA lightweight MCP server that provides read-only access to SQLite databases, allowing users to execute SELECT queries, list tables, and describe table schemas.Last updated -PythonMIT License