MySQL MCP服务器
一种安全的模型上下文协议(MCP)服务器,使大型语言模型(LLM)能够通过标准化的接口与MySQL数据库进行交互。该服务器提供具有全面安全控制的读写操作,使其成为人工智能驱动的数据库交互的理想选择。
🌟 特性
- 🛡️ 缺省巩固安全:只读模式,可选写操作
- 🚀 高性能:连接池和查询优化
- 🔐 SQL注入保护:参数化查询和标识符验证
- 📊 综合工具集:18个数据库操作工具
- ⚡ 速率限制:可配置的限制以防止滥用
- 📝 审计日志:JSON格式的完整操作历史记录
- 🔄 资源系统:将数据库模式作为MCP资源公开
- ⏱️ 查询超时:防止长时间运行的查询
- 🎯 结果限制:内存高效的结果处理
📋 目录
- 安装
- 配置
- 可用工具
- 安全功能
- 使用示例
- 建筑
- 故障排除
- 贡献
- 许可证
🚀 安装
先决条件
- Node.js 18或更高版本
- MySQL 5.7+或MariaDB 10.2+
- npm或yarn包管理器
步骤1:克隆和构建```bash
git clone https://github.com/yourusername/mav-mysql-mcp-server.git
cd mav-mysql-mcp-server
npm install
npm run build
### 步骤2:创建MySQL只读用户(推荐)
为了安全起见,请创建一个专用的只读用户:```bash
mysql -u root -p < setup-readonly-user.sql
或手动:```sql
CREATE USER 'mcp_readonly'@'localhost' IDENTIFIED BY 'secure_password';
GRANT SELECT ON your_database. TO 'mcp_readonly'@'localhost';
GRANT SHOW VIEW ON your_database. TO 'mcp_readonly'@'localhost';
FLUSH PRIVILEGES;
### 步骤3:配置MCP客户端
#### 适用于克劳德桌面
添加到您的Claude Desktop配置文件中:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**视窗**: `%APPDATA%\Claude\claude_desktop_config.json````json
{
"mcpServers": {
"mysql-myproject": {
"command": "node",
"args": ["/absolute/path/to/mav-mysql-mcp-server/build/index.js"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "mcp_readonly",
"MYSQL_PASSWORD": "secure_password",
"MYSQL_DATABASE": "your_database"
}
}
}
}
⚙️ 配置
环境变量
| 变量 | 描述 | 默认值 | 必填 |
|---|---|---|---|
MYSQL_HOST |
MySQL服务器主机名 | - | ✅ |
MYSQL_PORT |
MySQL服务器端口 | 3306 | ❌ |
MYSQL_USER |
MySQL用户名 | - | ✅ |
MYSQL_PASSWORD |
MySQL密码 | - | ✅ |
MYSQL_DATABASE |
默认数据库名称 | - | ✅ |
ALLOW_WRITE_OPERATIONS |
启用写入操作 | false | ❌ |
CONNECTION_LIMIT |
池中的最大连接数 | 5 | ❌ |
QUERY_TIMEOUT |
查询超时(毫秒) | 30000 | ❌ |
MAX_RESULTS |
每次查询返回的最大行数 | 1000 | ❌ |
RATE_LIMIT_PER_MINUTE |
每分钟允许查询 | 60 | ❌ |
RATE_LIMIT_PER_HOUR |
每小时允许查询 | 1000 | ❌ |
RATE_LIMIT_CONCURRENT |
最大并发查询数 | 10 | ❌ |
MCP_DEBUG |
启用调试日志记录 | false | ❌ |
示例.env文件```env
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=myapp_user
MYSQL_PASSWORD=secure_password_here
MYSQL_DATABASE=myapp_db
Security
ALLOW_WRITE_OPERATIONS=false
Performance
CONNECTION_LIMIT=10
QUERY_TIMEOUT=60000
MAX_RESULTS=5000
Rate Limiting
RATE_LIMIT_PER_MINUTE=100
RATE_LIMIT_PER_HOUR=2000
RATE_LIMIT_CONCURRENT=20
## 🛠️ 可用工具
### 只读工具(始终可用)
#### 1. `query` -执行SQL查询
安全地执行参数化SQL查询。```json
{
"sql": "SELECT * FROM users WHERE age > ? AND city = ?",
"params": [18, "New York"]
}
2. list_tables -列出数据库表
获取当前数据库中的所有表。```json
{}
返回:表名数组
#### 3. `describe_table` -获取表架构
获取有关表结构的详细信息。```json
{
"table": "users"
}
返回:具有类型、可空性、默认值等的列定义。
4. database_info -数据库统计
获取全面的数据库信息。```json
{}
返回:数据库版本、大小、表计数、字符集等。
#### 5. `show_indexes` -显示表索引
列出特定表的所有索引。```json
{
"table": "orders"
}
6. explain_query -查询执行计划
分析查询性能。```json
{
"sql": "SELECT * FROM orders JOIN users ON orders.user_id = users.id WHERE orders.total > 100"
}
#### 7. `show_constraints` -表约束
显示外键和唯一约束。```json
{
"table": "order_items"
}
写入操作工具(需要 ALLOW_WRITE_OPERATIONS=true)
8. insert -插入单行
在表中插入新行。```json
{
"table": "users",
"data": {
"name": "John Doe",
"email": "john@example.com",
"age": 30
}
}
#### 9. `update` -更新行
用条件更新现有行。```json
{
"table": "users",
"data": {
"status": "active",
"updated_at": "2024-01-01 00:00:00"
},
"where": {
"id": 123
}
}
10. delete -删除行
删除符合条件的行。```json
{
"table": "sessions",
"where": {
"expired": true
}
}
#### 11. `bulk_insert` -插入多行
在一次操作中高效地插入多行。```json
{
"table": "products",
"rows": [
{"name": "Product 1", "price": 19.99},
{"name": "Product 2", "price": 29.99},
{"name": "Product 3", "price": 39.99}
]
}
12. create_table -创建新表
使用指定列创建新表。```json
{
"table": "products",
"columns": [
{
"name": "id",
"type": "INT",
"primary": true,
"autoIncrement": true
},
{
"name": "name",
"type": "VARCHAR(255)",
"nullable": false
},
{
"name": "price",
"type": "DECIMAL(10,2)",
"nullable": false,
"default": "0.00"
},
{
"name": "created_at",
"type": "TIMESTAMP",
"default": "CURRENT_TIMESTAMP"
}
]
}
#### 13. `alter_table` -修改表结构
添加、删除、修改或重命名列。```json
{
"table": "users",
"operation": "add_column",
"column": {
"name": "phone",
"type": "VARCHAR(20)",
"nullable": true,
"after": "email"
}
}
操作: add_column, drop_column, modify_column, rename_column
14. drop_table -删除表
放下一张桌子(需要确认)。```json
{
"table": "old_logs",
"confirm": "DROP_TABLE_old_logs"
}
#### 15. `add_index` -创建索引
添加索引以提高查询性能。```json
{
"table": "orders",
"indexName": "idx_user_date",
"columns": ["user_id", "order_date"],
"unique": false
}
16. drop_index -删除索引
删除现有索引。```json
{
"table": "orders",
"indexName": "idx_user_date"
}
#### 17. `rename_table` -重命名表
重命名现有表。```json
{
"oldName": "user_profiles",
"newName": "profiles"
}
18. execute_procedure -调用存储过程
使用参数执行存储过程。```json
{
"procedure": "calculate_user_stats",
"params": [123, "2024-01-01"]
}
## 🔒 安全功能
### 1.访问控制
- **默认情况下为只读**:必须显式启用写入操作
- **系统表保护**:访问mysql。*,信息模式。*等被阻塞
- **敏感数据检测**:包含密码/令牌/秘密模式的查询被阻止
### 2.SQL注入防护
- **参数化查询**:所有用户输入都已正确转义
- **标识符验证**:表/列名必须是字母数字+下划线
- **查询模式匹配**:检测并阻止危险操作
### 3.操作限制
- **无文件操作**:进入OUTFILE,加载数据被阻止
- **没有权限更改**:格兰特,雷沃基被阻止
- **无系统命令**:系统功能被阻止
### 4.费率限制
- 每分钟查询限制
- 每小时查询限制
- 并发查询限制
- 达到限制时自动节流
### 5.审计追踪
所有操作都记录在:
- 时间戳
- 查询类型和详细信息
- 用户信息
- 执行时间
- 成功/失败状态
## 📚 使用示例
### 基本查询示例```javascript
// In Claude or another MCP client
const result = await use_mcp_tool({
server_name: "mysql-myproject",
tool_name: "query",
arguments: {
sql: "SELECT id, name, email FROM users WHERE created_at > ? ORDER BY created_at DESC LIMIT 10",
params: ["2024-01-01"]
}
});
创建带索引的表```javascript
// Create the table
await use_mcp_tool({
server_name: "mysql-myproject",
tool_name: "create_table",
arguments: {
table: "products",
columns: [
{ name: "id", type: "INT", primary: true, autoIncrement: true },
{ name: "sku", type: "VARCHAR(50)", nullable: false },
{ name: "name", type: "VARCHAR(255)", nullable: false },
{ name: "price", type: "DECIMAL(10,2)", nullable: false },
{ name: "category_id", type: "INT", nullable: false }
]
}
});
// Add indexes
await use_mcp_tool({
server_name: "mysql-myproject",
tool_name: "add_index",
arguments: {
table: "products",
indexName: "idx_sku",
columns: ["sku"],
unique: true
}
});
### 批量操作```javascript
// Bulk insert
await use_mcp_tool({
server_name: "mysql-myproject",
tool_name: "bulk_insert",
arguments: {
table: "inventory_updates",
rows: [
{ product_id: 1, quantity: 100, updated_by: "system" },
{ product_id: 2, quantity: 50, updated_by: "system" },
{ product_id: 3, quantity: 75, updated_by: "system" }
]
}
});
🏗️ 建筑
组件概述```
┌─────────────────┐ ┌──────────────────┐ ┌──────────────┐
│ MCP Client │────▶│ MCP Server │────▶│ MySQL │
│ (Claude) │◀────│ (This Tool) │◀────│ Database │
└─────────────────┘ └──────────────────┘ └──────────────┘
│ │ │
│ ├── Connection Pool │
│ ├── Query Validator │
│ ├── Rate Limiter │
│ └── Audit Logger │
│ │
└───────────── stdio (JSON-RPC) ────────────────┘
### 关键组件
1. **MCP协议处理程序** (`server.ts`)
- 处理工具和资源请求
- 通往合适处理者的路线
- 管理协议合规性
1. **数据库管理器** (`database.ts`)
- 连接池
- 查询执行
- 交易管理
- 安全验证
1. **安全层**
- 输入验证
- 查询分析
- 权限检查
- 速率限制
1. **记录系统** (`logger.ts`)
- 结构化JSON日志记录
- 审计跟踪
- 误差跟踪
- 性能指标
### 设计模式
- **工厂模式**:数据库连接创建
- **存储库模式**:数据库操作封装
- **策略模式**:用于各种操作的不同处理程序
- **防护图案**:多个验证层
## 🔧 故障排除
### 常见问题
#### 连接被拒绝```
Error: connect ECONNREFUSED 127.0.0.1:3306
解决方案:确保MySQL在指定的主机/端口上运行并可访问。
认证失败```
Error: Access denied for user 'username'@'localhost'
**解决方案**:验证用户名、密码和用户权限。
#### 速率限制已超出```
Error: Rate limit exceeded. Please wait before making more requests.
解决方案:降低查询频率或增加配置中的速率限制。
查询超时```
Error: Query timeout of 30000ms exceeded
**解决方案**:优化您的查询或增加query_TIMEOUT设置。
### 调试模式
启用调试日志记录以获取详细信息:```bash
MCP_DEBUG=true node build/index.js
健康检查
测试您的连接:```javascript
await use_mcp_tool({
server_name: "mysql-myproject",
tool_name: "database_info",
arguments: {}
});
## 🤝 贡献
我们欢迎捐款!请查看我们的 贡献指南 了解详情。
### 开发设置```bash
# Clone the repository
git clone https://github.com/yourusername/mav-mysql-mcp-server.git
cd mav-mysql-mcp-server
# Install dependencies
npm install
# Run in development mode
npm run dev
# Run tests
npm test
# Build for production
npm run build
代码风格
- 具有严格模式的TypeScript
- 包括ESLint配置
- 格式化预处理
- 常规承诺
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🙏 致谢
- 建立在 模型上下文协议 通过Anthropic
- 用途 mysql2 用于MySQL连接
- 灵感来自OWASP的安全最佳实践
📞 支持
- 问题: GitHub问题
- 讨论: GitHub讨论
- 安全:向报告漏洞derrick@derricksiawor.com
由以下材料制成❤️ 作者Derrick S.K.Siawor
