MCP MySQL Server 使用指南

简介

MCP MySQL Server是一个基于Model Context Protocol (MCP)的数据库服务端，允许AI模型通过标准化接口安全地与MySQL数据库交互。本指南将详细介绍如何安装、配置和使用该服务。

地址： github.com/huangfeng19...

安装方法

前提条件

Node.js 14.x或更高版本
npm 6.x或更高版本
MySQL数据库服务器
网络连接（用于安装依赖包）

安装步骤

方法1：通过Smithery安装（推荐）

bash 复制代码

npx -y @smithery/cli install @fhuang/mcp-mysql-server --client claude

方法2：手动安装

bash 复制代码

# 创建项目目录
mkdir mcp-mysql-server && cd mcp-mysql-server

# 初始化项目
npm init -y

# 安装依赖
npm install @fhuang/mcp-mysql-server

配置指南

MCP MySQL Server支持两种配置方式：命令行参数和环境变量。

方式1：使用MySQL连接URL（推荐）

bash 复制代码

npx @fhuang/mcp-mysql-server mysql://user:password@localhost:3306/database

方式2：使用环境变量

创建.env文件：

ini 复制代码

MYSQL_HOST=localhost
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database
MYSQL_PORT=3306

# 连接池配置
CONNECTION_LIMIT=10
QUEUE_LIMIT=0

然后启动服务：

bash 复制代码

npx @fhuang/mcp-mysql-server

方式3：在MCP客户端中配置

json 复制代码

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@fhuang/mcp-mysql-server"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

工具使用详解

1. connect_db - 连接数据库

建立与MySQL数据库的连接。

参数：

host: 数据库主机地址
user: 数据库用户名
password: 数据库密码
database: 数据库名称
port (可选): 数据库端口，默认为3306

示例：

typescript 复制代码

use_mcp_tool({
  server_name: "mysql",
  tool_name: "connect_db",
  arguments: {
    host: "localhost",
    user: "root",
    password: "password",
    database: "mydb"
  }
});

2. query - 执行查询

执行SELECT查询语句，支持参数化查询以防止SQL注入。

参数：

sql: SELECT查询语句
params (可选): 查询参数数组

示例：

typescript 复制代码

// 简单查询
use_mcp_tool({
  server_name: "mysql",
  tool_name: "query",
  arguments: {
    sql: "SELECT * FROM users"
  }
});

// 参数化查询
use_mcp_tool({
  server_name: "mysql",
  tool_name: "query",
  arguments: {
    sql: "SELECT * FROM users WHERE age > ? AND status = ?",
    params: [18, "active"]
  }
});

3. execute - 执行写操作

执行INSERT、UPDATE或DELETE语句，支持参数化查询。

参数：

sql: INSERT/UPDATE/DELETE语句
params (可选): 查询参数数组

示例：

typescript 复制代码

// 插入数据
use_mcp_tool({
  server_name: "mysql",
  tool_name: "execute",
  arguments: {
    sql: "INSERT INTO users (name, email) VALUES (?, ?)",
    params: ["John Doe", "john@example.com"]
  }
});

// 更新数据
use_mcp_tool({
  server_name: "mysql",
  tool_name: "execute",
  arguments: {
    sql: "UPDATE users SET status = ? WHERE id = ?",
    params: ["inactive", 123]
  }
});

4. list_tables - 列出所有表

获取数据库中所有表的列表。

参数： 无

示例：

typescript 复制代码

use_mcp_tool({
  server_name: "mysql",
  tool_name: "list_tables",
  arguments: {}
});

5. describe_table - 查看表结构

获取指定表的结构信息，包括字段名、数据类型和约束条件。

参数：

table: 表名

示例：

typescript 复制代码

use_mcp_tool({
  server_name: "mysql",
  tool_name: "describe_table",
  arguments: {
    table: "users"
  }
});

6. show_statement - 执行SHOW语句

执行MySQL SHOW语句，用于获取数据库服务器状态和配置信息。

参数：

sql: SHOW语句

示例：

typescript 复制代码

// 查看数据库参数
use_mcp_tool({
  server_name: "mysql",
  tool_name: "show_statement",
  arguments: {
    sql: "SHOW VARIABLES LIKE 'max_connections'"
  }
});

// 查看连接状态
use_mcp_tool({
  server_name: "mysql",
  tool_name: "show_statement",
  arguments: {
    sql: "SHOW STATUS LIKE 'Threads_connected'"
  }
});

7. explain - 分析查询性能

使用EXPLAIN语句分析查询执行计划，帮助识别性能瓶颈。

参数：

sql: 需要分析的SELECT语句

示例：

typescript 复制代码

use_mcp_tool({
  server_name: "mysql",
  tool_name: "explain",
  arguments: {
    sql: "SELECT * FROM users WHERE age > 18 AND status = 'active'"
  }
});

错误处理

MCP MySQL Server提供详细的错误信息，常见错误及解决方法：

连接错误

错误信息 : DATABASE_CONNECTION_FAILED
可能原因: MySQL服务器未运行、连接参数错误、网络问题
解决方法: 检查MySQL服务器状态、验证连接参数、测试网络连接

查询错误

错误信息 : DATABASE_QUERY_FAILED 或 DATABASE_EXECUTE_FAILED
可能原因: SQL语法错误、权限不足、表或字段不存在
解决方法: 检查SQL语法、验证用户权限、确认表结构

参数错误

错误信息 : INVALID_PARAMS
可能原因: 缺少必填参数、参数类型错误
解决方法: 检查参数是否完整、验证参数类型

性能优化

连接池配置

通过环境变量调整连接池参数：

ini 复制代码

# 最大连接数
CONNECTION_LIMIT=20

# 排队限制，0表示无限制
QUEUE_LIMIT=50

查询优化

使用参数化查询提高性能和安全性
对频繁查询的字段创建索引
使用explain工具分析慢查询
避免SELECT *，只查询需要的字段

安全最佳实践

保护敏感信息
- 不要在代码中硬编码数据库凭证
- 使用环境变量或配置文件存储敏感信息
- 限制数据库用户权限
防止SQL注入
- 始终使用参数化查询
- 避免直接拼接SQL字符串
日志管理
- 定期审查日志文件
- 不要在日志中记录密码等敏感信息

常见问题

Q: 如何查看服务器日志？

A: 日志文件默认保存在项目根目录的server.log文件中。

Q: 连接池 connections 和 threads_connected 有什么区别？

A: connections是应用程序级别的连接池配置，而threads_connected是MySQL服务器级别的实际连接数。

Q: 如何更新MCP MySQL Server到最新版本？

A: 使用命令 npm update @fhuang/mcp-mysql-server

Q: 服务启动后无法连接到数据库，如何排查？

检查MySQL服务器是否正常运行
验证连接参数是否正确
检查防火墙设置
查看日志文件获取详细错误信息

高级功能

事务支持

虽然当前版本未直接提供事务API，但可以通过execute工具执行事务相关语句：

typescript 复制代码

// 开始事务
use_mcp_tool({
  server_name: "mysql",
  tool_name: "execute",
  arguments: {
    sql: "START TRANSACTION"
  }
});

// 提交事务
use_mcp_tool({
  server_name: "mysql",
  tool_name: "execute",
  arguments: {
    sql: "COMMIT"
  }
});

// 回滚事务
use_mcp_tool({
  server_name: "mysql",
  tool_name: "execute",
  arguments: {
    sql: "ROLLBACK"
  }
});

监控连接池状态

typescript 复制代码

// 查看连接池状态
use_mcp_tool({
  server_name: "mysql",
  tool_name: "show_statement",
  arguments: {
    sql: "SHOW STATUS LIKE 'Threads_connected'"
  }
});

总结

MCP MySQL Server提供了一套完整的工具集，使AI模型能够安全、高效地与MySQL数据库交互。通过本指南，您应该能够快速安装、配置和使用该服务，并利用其提供的各种功能进行数据库操作和性能分析。

如需更多帮助，请查看项目GitHub仓库或提交issue。