Mysql MCP Local Server

MySQL MCP 服务器 v2.0

一个全面的MySQL数据库操作模型上下文协议（MCP）服务器，配备37个强大工具，具备高级错误处理、日志记录和事务支持功能。

🚀 特性

• ✅ 37款MySQL工具完整的数据库管理工具包
• ✅ 核心业务/核心运营SELECT、INSERT、UPDATE、DELETE 查询
• ✅ 模式管理创建/删除表、索引，修改结构
• ✅（正确/对号） 高级查询连接、聚合、批量操作、插入更新（或“合并插入”）
• ✅ 数据库管理备份、恢复、优化、分析
• ✅ 用户与安全用户管理和权限设置（如支持）
• ✅ 监控与性能查询分析、状态监控、表大小
• ✅ 进口/出口CSV、JSON数据交换，表格克隆
• ✅ 事务支持带回滚的多查询事务
• ✅ 连接管理池化、健康检查、自动重连
• ✅ 错误处理全面的错误处理，附带详细的日志记录
• ✅ 测试完整的测试套件，涵盖所有37个工具

📋 先决条件

• Node.js 18.0.0 或更高版本
• MySQL服务器5.7版本及以上或8.0版本及以上
• 数据库凭据已配置

🛠️ 安装

1. 安装依赖项：

npm install

1. 通过更新以下信息来配置您的数据库连接 .env 文件：

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

🎯 使用方法

启动服务器

# Production mode
npm start

# Development mode with auto-restart
npm run dev

运行测试

npm test

🔧 可用工具（共37个）

核心数据库操作（4种工具）

1. mysql_query

在数据库上执行SELECT查询。

参数：

• sql (字符串，必填)：SQL SELECT 查询语句
• params （数组，可选）：预编译语句的参数

示例：

{
  "sql": "SELECT * FROM users WHERE age > ? AND department = ?",
  "params": [25, "IT"]
}

2. mysql_insert

将数据插入到表中。

参数：

• table （字符串，必填）：表名
• data (对象，必需)：列名和值的键值对

示例：

{
  "table": "users",
  "data": {
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30,
    "department": "Engineering"
  }
}

3. mysql_update

更新表中的数据。

参数：

• table (字符串，必填)：表名
• data (对象，必需)：要更新的列的键值对
• where (对象，必需)：WHERE 条件

示例：

{
  "table": "users",
  "data": {
    "age": 31,
    "department": "Senior Engineering"
  },
  "where": {
    "email": "john@example.com"
  }
}

4. mysql_delete

从表中删除数据。

参数：

• table (字符串，必填)：表名
• where (对象，必需): WHERE 条件

示例：

{
  "table": "users",
  "where": {
    "email": "john@example.com"
  }
}

模式管理工具（5种工具）

5. mysql_create_table

创建带有列定义的新表。

参数：

• table_name （字符串，必填）：要创建的表的名称
• columns (数组，必需)：列定义的数组
• options (对象，可选)：额外的表格选项

示例：

{
  "table_name": "products",
  "columns": [
    "id INT AUTO_INCREMENT PRIMARY KEY",
    "name VARCHAR(255) NOT NULL",
    "price DECIMAL(10,2)",
    "created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP"
  ],
  "options": {
    "engine": "InnoDB",
    "charset": "utf8mb4"
  }
}

6. mysql_drop_table

安全地删除表。

参数：

• table_name （字符串，必填）：要删除的表的名称
• if_exists （布尔值，可选）：使用 IF EXISTS 子句

示例：

{
  "table_name": "old_products",
  "if_exists": true
}

7. mysql_alter_table

修改表结构（添加/删除列）。

参数：

• table_name (字符串，必填)：要修改的表的名称
• action （字符串，必填）：要执行的操作（添加、删除、修改）
• column_definition （字符串，必填）：列定义或名称

示例：

{
  "table_name": "users",
  "action": "ADD",
  "column_definition": "phone VARCHAR(20)"
}

8. mysql_create_index

创建数据库索引。

参数：

• table_name (字符串，必填): 表名
• index_name (字符串，必填)：索引名称
• columns (数组，必需)：要索引的列
• unique (布尔值，可选)：创建唯一索引

示例：

{
  "table_name": "users",
  "index_name": "idx_email",
  "columns": ["email"],
  "unique": true
}

9. mysql_drop_index

移除索引。

参数：

• table_name (字符串，必填)：表名
• index_name (字符串，必需): 要删除的索引名称

示例：

{
  "table_name": "users",
  "index_name": "idx_email"
}

高级查询工具（5种工具）

10. mysql_aggregate_query

执行聚合函数（COUNT、SUM、AVG 等）。

参数：

• table (字符串，必填)：表名
• aggregates (数组，必需)：聚合函数
• where (对象，可选)：WHERE 条件
• group_by (数组，可选)：GROUP BY 列

示例：

{
  "table": "orders",
  "aggregates": ["COUNT(*) as total_orders", "SUM(amount) as total_revenue"],
  "where": {"status": "completed"},
  "group_by": ["customer_id"]
}

11. mysql_join_query

执行复杂的JOIN操作。

参数：

• main_table (字符串，必填)：主表
• joins (数组，必需)：连接定义
• select （数组，必需）：要选择的列
• where (对象，可选)：WHERE 条件

示例：

{
  "main_table": "users",
  "joins": [
    {
      "type": "INNER",
      "table": "orders",
      "on": "users.id = orders.user_id"
    }
  ],
  "select": ["users.name", "users.email", "orders.total"],
  "where": {"orders.status": "completed"}
}

12. mysql_bulk_insert

高效地插入多条记录。

参数：

• table (字符串，必填)：表名
• data (数组，必需)：要插入的对象数组

示例：

{
  "table": "products",
  "data": [
    {"name": "Product A", "price": 19.99, "category": "Electronics"},
    {"name": "Product B", "price": 29.99, "category": "Electronics"},
    {"name": "Product C", "price": 39.99, "category": "Books"}
  ]
}

13. mysql_upsert

“INSERT ON DUPLICATE KEY UPDATE”操作。

参数：

• table (字符串，必填)：表名
• data （对象，必需）：要插入/更新的数据
• update_on_duplicate (对象，可选)：在重复时要更新的列

示例：

{
  "table": "products",
  "data": {"sku": "ABC123", "name": "Product A", "price": 24.99},
  "update_on_duplicate": {"price": "VALUES(price)", "updated_at": "NOW()"}
}

14. mysql_search

使用LIKE/MATCH操作进行全文搜索。

参数：

• table （字符串，必填）：表名
• search_columns (数组，必填)：要搜索的列
• search_term （字符串，必填）：搜索词
• match_mode （字符串，可选）：LIKE 或 MATCH（默认：LIKE）

示例：

{
  "table": "articles",
  "search_columns": ["title", "content"],
  "search_term": "database optimization",
  "match_mode": "LIKE"
}

数据库管理工具（6种工具）

15. mysql_show_databases

列出服务器上的所有数据库。

参数： 无

16. mysql_create_database

创建新数据库。

参数：

• database_name (字符串，必填)：要创建的数据库名称
• charset （字符串，可选）：字符集
• collation (字符串，可选)：排序规则

示例：

{
  "database_name": "new_project",
  "charset": "utf8mb4",
  "collation": "utf8mb4_unicode_ci"
}

17. mysql_backup_table

将表格数据导出到SQL。

参数：

• table_name (字符串，必填)：要备份的表
• include_data (布尔值，可选)：是否包含数据（默认：true）
• file_path (字符串，可选)：输出文件路径

示例：

{
  "table_name": "users",
  "include_data": true,
  "file_path": "./backups/users_backup.sql"
}

18. mysql_restore_table

从SQL备份中导入数据。

参数：

• file_path （字符串，必填）：SQL 备份文件的路径
• table_name (字符串，可选)：要恢复的特定表

示例：

{
  "file_path": "./backups/users_backup.sql",
  "table_name": "users"
}

19. mysql_optimize_table

优化表格性能。

参数：

• table_names (数组，必需)：要优化的表格

示例：

{
  "table_names": ["users", "orders", "products"]
}

20. mysql_analyze_table

分析表统计信息。

参数：

• table_names （数组，必需）：要分析的表格

示例：

{
  "table_names": ["users", "orders"]
}

用户与安全工具（4种工具）

21. mysql_show_users

列出数据库用户。

参数： 无

22. mysql_show_grants

显示用户权限。

参数：

• username （字符串，可选）：特定用户（默认：当前用户）

示例：

{
  "username": "app_user"
}

23. mysql_create_user

创建数据库用户。

参数：

• username （字符串，必填）：用户名
• password (字符串，必填)：密码
• host (字符串，可选)：主机（默认：%）

示例：

{
  "username": "new_user",
  "password": "secure_password",
  "host": "localhost"
}

24. mysql_grant_privileges

授予用户权限。

参数：

• username （字符串，必填）：用户名
• privileges （数组，必需）：要授予的权限
• database (字符串，可选)：数据库名称
• table (字符串，可选)：表名

示例：

{
  "username": "app_user",
  "privileges": ["SELECT", "INSERT", "UPDATE"],
  "database": "app_db",
  "table": "*"
}

监控与性能工具（5种工具）

25. mysql_show_processlist

显示正在运行的查询。

参数：

• full (布尔值，可选)：显示完整查询

示例：

{
  "full": true
}

26. mysql_explain_query

分析查询执行计划。

参数：

• sql (字符串，必填)：要分析的查询
• format (字符串，可选)：输出格式 (TRADITIONAL, JSON)

示例：

{
  "sql": "SELECT * FROM users WHERE age > 25 ORDER BY created_at",
  "format": "JSON"
}

27. mysql_show_status

数据库服务器状态。

参数：

• pattern (字符串，可选)：状态变量模式

示例：

{
  "pattern": "Connections"
}

28. mysql_show_variables

服务器配置变量。

参数：

• pattern (字符串，可选)：变量名模式

示例：

{
  "pattern": "innodb%"
}

29. mysql_table_size

获取表的大小信息。

参数：

• table_names (数组，可选)：特定的表格（默认：全部）

示例：

{
  "table_names": ["users", "orders"]
}

数据导入/导出工具（4种工具）

30. mysql_export_csv

将查询结果导出为CSV文件。

参数：

• sql (字符串，必填)：要导出的查询
• file_path (字符串，必填)：输出CSV文件路径
• headers (布尔值，可选)：是否包含标题

示例：

{
  "sql": "SELECT name, email, age FROM users",
  "file_path": "./exports/users.csv",
  "headers": true
}

31. mysql_import_csv

将CSV数据导入表格。

参数：

• table_name （字符串，必填）：目标表
• file_path (字符串，必填)：CSV 文件路径
• columns （数组，可选）：列映射
• skip_header (布尔值，可选)：跳过第一行

示例：

{
  "table_name": "users",
  "file_path": "./imports/users.csv",
  "columns": ["name", "email", "age"],
  "skip_header": true
}

32. mysql_export_json

将数据导出为JSON格式。

参数：

• sql (字符串，必填)：要导出的查询
• file_path (字符串，必填)：输出JSON文件路径
• pretty (布尔值，可选)：以易读格式打印 JSON

示例：

{
  "sql": "SELECT * FROM products WHERE category = 'Electronics'",
  "file_path": "./exports/electronics.json",
  "pretty": true
}

33. mysql_clone_table

复制表结构/数据。

参数：

• source_table (字符串，必填): 源表名
• target_table (字符串，必填)：目标表名
• include_data (布尔型，可选)：复制数据（默认：true）
• include_indexes (布尔值，可选)：复制索引（默认：true）

示例：

{
  "source_table": "users",
  "target_table": "users_backup",
  "include_data": true,
  "include_indexes": false
}

实用工具（4种工具）

34. mysql_transaction

在一个事务中执行多个查询。

参数：

• queries (数组，必需): 查询对象的数组

示例：

{
  "queries": [
    {
      "sql": "INSERT INTO users (name, email) VALUES (?, ?)",
      "params": ["Alice", "alice@example.com"]
    },
    {
      "sql": "UPDATE users SET last_login = NOW() WHERE email = ?",
      "params": ["alice@example.com"]
    }
  ]
}

35. mysql_list_tables

列出数据库中的所有表。

参数：

• pattern (字符串，可选)：表名模式

示例：

{
  "pattern": "user%"
}

36. mysql_describe_table

获取有关表结构的详细信息。

参数：

• table_name (字符串，必填)：表名

示例：

{
  "table_name": "users"
}

37. mysql_health_check

检查数据库连接的健康状况。

参数： 无

⚙️ 配置

服务器使用以下环境变量：

📝 日志记录

服务器使用Winston进行全面日志记录：

• 控制台开发用的彩色输出
• 文件： logs/combined.log 对于所有日志
• 文件： logs/error.log 仅用于错误日志

日志级别： error， warn， info， debug

🛡️ 错误处理

全面的错误处理包括：

• 连接错误自动重连和连接池
• SQL 错误带有SQL状态和错误代码的详细错误信息
• 交易错误故障时自动回滚
• 验证错误对所有操作进行输入验证
• 权限错误优雅地处理权限不足的情况
• 文件输入/输出错误导入/导出操作的正确错误处理

🧪 测试

该综合测试套件验证了全部37个工具：

• 数据库连接和健康检查
• 对各种数据类型执行所有CRUD操作
• 模式管理操作
• 高级查询操作（连接、聚合、批量操作）
• 事务处理，包括提交和回滚
• 数据库管理工具
• 用户和安全操作（在权限允许的情况下）
• 监控和性能工具
• 导入/导出功能
• 对无效操作进行错误处理

使用以下方式运行测试：

npm test

📁 项目结构

mysql-mcp-server/
├── src/
│   ├── index.js          # Main MCP server with all 37 tools
│   └── database.js       # Database connection and operations
├── test/
│   └── test-operations.js # Comprehensive test suite
├── logs/
│   └── .gitkeep         # Logs directory
├── .env                 # Environment configuration
├── package.json         # Project dependencies
└── README.md           # This documentation

🔒 安全考量

• 使用预编译语句来防止SQL注入
• 设置限制的连接池以防止资源耗尽
• 未记录任何敏感数据（密码、连接字符串）
• 对所有操作进行输入验证和清理
• 安全的文件处理，用于导入/导出操作
• 提供恰当的错误信息，同时不暴露系统内部细节

🚀 性能特性

• 连接池以优化性能
• 针对大型数据集的批量操作
• 查询优化工具与分析
• 表优化和维护工具
• 高效的交易处理
• 大数据导出的流式处理

📊 工具类别概述

| 完整的MySQL管理工具包 |

📄 许可证

______________________________________________________________________

麻省理工学院许可证（MIT License） MySQL MCP 服务器 v2.0