# MySQL ReadOnly MCP Server

🔒 **生产就绪** 的 MySQL 只读 MCP (Model Context Protocol) 服务器，提供安全、高性能的数据库查询服务。

## ✨ 核心特性

- 🔒 **只读安全**: 仅允许 SELECT 查询，多层安全防护
- 🚀 **高性能**: 连接池、自动LIMIT、查询优化
- 🛡️ **企业级安全**: SQL注入防护、配置验证、SSL支持
- 🧪 **测试覆盖**: 17个全面的单元测试
- 📝 **TypeScript**: 完整类型支持
- 🔧 **多平台支持**: Claude Desktop、Claude Code、Gemini CLI

## 🚀 快速开始

### 1. 安装依赖

```bash
git clone https://github.com/jway8975/mysql-readonly-mcp.git
cd mysql-readonly-mcp
npm install
```

### 2. 配置数据库连接

```bash
cp .env.example .env
```

编辑 `.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. 构建项目

```bash
npm run build
```

### 4. 配置到您的AI客户端

选择以下任一配置方式：

- [Claude Desktop](#claude-desktop-配置)
- [Claude Code](#claude-code-配置)
- [Gemini CLI](#gemini-cli-配置)

## 🔧 配置方法

### Claude Desktop 配置

找到 Claude Desktop 配置文件：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

添加以下配置：

```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` 文件。在项目根目录创建：

```bash
# 创建 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. **构建项目**：
```bash
npm run build
```

2. **设置环境变量**：
```bash
export MYSQL_HOST="localhost"
export MYSQL_USER="your_username"
export MYSQL_PASSWORD="your_password"
export MYSQL_DATABASE="your_database"
```

3. **验证配置**：
```bash
# Claude Code 会自动发现并配置 MCP 工具
claude-code "列出数据库中的所有表"
```

### Gemini CLI 配置

1. **安装 Gemini CLI**：
```bash
npm install -g @google/generative-ai-cli
```

2. **创建 MCP 配置文件**：
```bash
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**：
```bash
export GEMINI_MCP_CONFIG="$HOME/.gemini/mcp_config.json"
export GEMINI_API_KEY="your_gemini_api_key"
```

4. **测试连接**：
```bash
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 语句）

**示例**：
```json
{
  "query": "SELECT * FROM users WHERE age > 18 ORDER BY name LIMIT 10"
}
```

### 2. `mysql_list_tables` - 列出表
列出数据库中的所有表。

**参数**：
- `database` (string, 可选): 数据库名称（默认使用配置的数据库）

**示例**：
```json
{
  "database": "my_app_db"
}
```

### 3. `mysql_describe_table` - 表结构
获取表的结构和列信息。

**参数**：
- `table` (string, 必需): 要描述的表名
- `database` (string, 可选): 数据库名称

**示例**：
```json
{
  "table": "users",
  "database": "my_app_db"
}
```

### 4. `mysql_list_databases` - 列出数据库
列出所有可用的数据库（排除系统数据库）。

**参数**：无

## 🔒 安全特性

- **多层只读验证**: 严格的 SELECT 语句检查
- **SQL注入防护**: 检测危险关键词和注入模式
- **自动LIMIT**: 为查询添加默认限制，防止大数据集
- **配置验证**: 启动时验证必需配置
- **连接池**: 高效的连接管理，防止连接泄露
- **SSL支持**: 加密数据库连接

## 🧪 测试

```bash
# 运行所有测试
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"`: 尝试执行非只读查询

## 🚀 开发

### 开发模式
```bash
npm run dev
```

### 构建生产版本
```bash
npm run build
```

### 运行生产版本
```bash
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](LICENSE) 文件了解详情。

## 🆘 支持

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

1. 查看 [故障排除](#故障排除) 部分
2. 检查 [Issues](https://github.com/jway8975/mysql-readonly-mcp/issues) 页面
3. 创建新的 Issue 描述您的问题

---

**🎉 感谢使用 MySQL ReadOnly MCP Server！**

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