MySQL ReadOnly MCP Server
🔒 生产就绪 的 MySQL 只读 MCP (Model Context Protocol) 服务器，提供安全、高性能的数据库查询服务。
✨ 核心特性
- 🔒 只读安全: 仅允许 SELECT 查询，多层安全防护
- 🚀 高性能: 连接池、自动LIMIT、查询优化
- 🛡️ 企业级安全: SQL注入防护、配置验证、SSL支持
- 🧪 测试覆盖: 17个全面的单元测试
- 📝 TypeScript: 完整类型支持
- 🔧 多平台支持: Claude Desktop、Claude Code、Gemini CLI
🚀 快速开始
1. 安装依赖
git clone https://github.com/jway8975/mysql-readonly-mcp.git
cd mysql-readonly-mcp
npm install
2. 配置数据库连接
cp .env.example .env
编辑 .env 文件：
# 基本连接配置
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=your_mysql_username
MYSQL_PASSWORD=your_mysql_password
MYSQL_DATABASE=your_database_name
# SSL 配置（可选）
# MYSQL_SSL_CA=path/to/ca.pem
# MYSQL_SSL_CERT=path/to/cert.pem
# MYSQL_SSL_KEY=path/to/key.pem
# MYSQL_SSL_REJECT_UNAUTHORIZED=true
3. 构建项目
npm run build
4. 配置到您的AI客户端
选择以下任一配置方式：
🔧 配置方法
Claude Desktop 配置
找到 Claude Desktop 配置文件：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
添加以下配置：
{
"mcpServers": {
"mysql-readonly": {
"command": "node",
"args": ["完整路径/mysql-readonly-mcp/dist/index.js"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "your_username",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database"
}
}
}
}
⚠️ 重要提醒：
- 使用绝对路径，例如：
/Users/username/projects/mysql-readonly-mcp/dist/index.js - 确保路径中有正确的项目名称
mysql-readonly-mcp - 配置完成后重启 Claude Desktop
Claude Code 配置
Claude Code 会自动识别项目中的 .claude_config 文件。在项目根目录创建：
# 创建 Claude Code 配置文件
cat > .claude_config << 'EOF'
tools:
mysql-readonly:
type: mcp
command: node
args: ["./dist/index.js"]
env:
MYSQL_HOST: ${MYSQL_HOST}
MYSQL_PORT: ${MYSQL_PORT}
MYSQL_USER: ${MYSQL_USER}
MYSQL_PASSWORD: ${MYSQL_PASSWORD}
MYSQL_DATABASE: ${MYSQL_DATABASE}
EOF
使用步骤：
- 构建项目：
npm run build
- 设置环境变量：
export MYSQL_HOST="localhost"
export MYSQL_USER="your_username"
export MYSQL_PASSWORD="your_password"
export MYSQL_DATABASE="your_database"
- 验证配置：
# Claude Code 会自动发现并配置 MCP 工具
claude-code "列出数据库中的所有表"
Gemini CLI 配置
- 安装 Gemini CLI：
npm install -g @google/generative-ai-cli
- 创建 MCP 配置文件：
mkdir -p ~/.gemini
cat > ~/.gemini/mcp_config.json << 'EOF'
{
"servers": {
"mysql-readonly": {
"command": "node",
"args": ["完整路径/mysql-readonly-mcp/dist/index.js"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_USER": "your_username",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database"
}
}
}
}
EOF
- 配置 Gemini CLI：
export GEMINI_MCP_CONFIG="$HOME/.gemini/mcp_config.json"
export GEMINI_API_KEY="your_gemini_api_key"
- 测试连接：
gemini "请帮我查询用户表的前10条记录" --use-mcp mysql-readonly
📋 环境变量说明
| 变量名 | 必需 | 默认值 | 说明 |
|---|---|---|---|
MYSQL_HOST | ✅ | localhost | MySQL 服务器地址 |
MYSQL_PORT | ❌ | 3306 | MySQL 服务器端口 |
MYSQL_USER | ✅ | - | MySQL 用户名 |
MYSQL_PASSWORD | ✅ | - | MySQL 密码 |
MYSQL_DATABASE | ❌ | - | 默认连接的数据库 |
MYSQL_SSL_CA | ❌ | - | SSL CA 证书路径 |
MYSQL_SSL_CERT | ❌ | - | SSL 客户端证书路径 |
MYSQL_SSL_KEY | ❌ | - | SSL 客户端密钥路径 |
MYSQL_SSL_REJECT_UNAUTHORIZED | ❌ | true | 是否拒绝未授权的 SSL 证书 |
🛠️ 可用工具
1. mysql_query - 执行SQL查询
执行只读 SQL 查询。
参数：
query(string, 必需): 要执行的 SQL 查询（仅允许 SELECT 语句）
示例：
{
"query": "SELECT * FROM users WHERE age > 18 ORDER BY name LIMIT 10"
}
2. mysql_list_tables - 列出表
列出数据库中的所有表。
参数：
database(string, 可选): 数据库名称（默认使用配置的数据库）
示例：
{
"database": "my_app_db"
}
3. mysql_describe_table - 表结构
获取表的结构和列信息。
参数：
table(string, 必需): 要描述的表名database(string, 可选): 数据库名称
示例：
{
"table": "users",
"database": "my_app_db"
}
4. mysql_list_databases - 列出数据库
列出所有可用的数据库（排除系统数据库）。
参数：无
🔒 安全特性
- 多层只读验证: 严格的 SELECT 语句检查
- SQL注入防护: 检测危险关键词和注入模式
- 自动LIMIT: 为查询添加默认限制，防止大数据集
- 配置验证: 启动时验证必需配置
- 连接池: 高效的连接管理，防止连接泄露
- SSL支持: 加密数据库连接
🧪 测试
# 运行所有测试
npm test
# 运行测试并生成覆盖率报告
npm run test:coverage
# 监视模式运行测试
npm run test:watch
📊 性能优化
- 连接池: 复用数据库连接，减少连接开销
- 查询限制: 自动添加 LIMIT 子句，防止大查询
- 智能缓存: 优化重复查询性能
- 内存管理: 流式处理大型结果集
🔍 故障排除
连接问题
- ✅ 检查 MySQL 服务是否运行
- ✅ 验证
.env文件中的凭据 - ✅ 确保用户具有数据库的 SELECT 权限
- ✅ 检查网络连接和防火墙设置
配置问题
- ✅ 确保使用了绝对路径
- ✅ 验证环境变量设置
- ✅ 检查 SSL 配置（如适用）
常见错误
"Access denied": 检查用户名/密码和权限"Connection refused": MySQL 服务未运行或端口错误"Unknown database": 数据库不存在"Only SELECT statements are allowed": 尝试执行非只读查询
🚀 开发
开发模式
npm run dev
构建生产版本
npm run build
运行生产版本
npm start
📈 版本历史
- v1.0.0 - 初始版本，基础功能
- v1.1.0 - 添加连接池和性能优化
- v1.2.0 - 增强安全特性和测试覆盖
🤝 贡献
- Fork 仓库
- 创建特性分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'Add amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
📄 许可证
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
🆘 支持
如果您遇到问题或有疑问，请：
🎉 感谢使用 MySQL ReadOnly MCP Server！
现在您可以安全地让 AI 助手查询您的 MySQL 数据库了。