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 Code
• Gemini CLI

🔧 配置方法

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

使用步骤：

1. 构建项目：

npm run build

2. 设置环境变量：

export MYSQL_HOST="localhost"
export MYSQL_USER="your_username"
export MYSQL_PASSWORD="your_password"
export MYSQL_DATABASE="your_database"

3. 验证配置：

# Claude Code 会自动发现并配置 MCP 工具
claude-code "列出数据库中的所有表"

Gemini CLI 配置

1. 安装 Gemini CLI：

npm install -g @google/generative-ai-cli

2. 创建 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

3. 配置 Gemini CLI：

export GEMINI_MCP_CONFIG="$HOME/.gemini/mcp_config.json"
export GEMINI_API_KEY="your_gemini_api_key"

4. 测试连接：

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 - 增强安全特性和测试覆盖

🤝 贡献

1. Fork 仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🆘 支持

如果您遇到问题或有疑问，请：

1. 查看 故障排除 部分
2. 检查 Issues 页面
3. 创建新的 Issue 描述您的问题

---

🎉 感谢使用 MySQL ReadOnly MCP Server！

现在您可以安全地让 AI 助手查询您的 MySQL 数据库了。