MCP MySQL Server是一款基于Model Context Protocol (MCP)的数据库服务端，旨在使AI模型能够通过标准化接口安全地与MySQL数据库进行交互。本指南详细介绍了该服务的安装、配置和使用方法，包括推荐的Smithery安装方式、命令行参数及环境变量配置，以及多种工具函数的使用，如连接数据库、执行查询、更新数据、列出表、查看表结构、执行SHOW语句和分析查询性能。此外，还涵盖了错误处理、性能优化建议、安全最佳实践、常见问题解答以及事务支持等高级功能，帮助用户快速上手并充分利用MCP MySQL Server。

🚀 **安装与配置简便**：MCP MySQL Server支持通过Smithery CLI（推荐）或手动npm安装，并提供了多种配置方式，包括MySQL连接URL、环境变量（通过.env文件）以及在MCP客户端中进行集中配置，满足不同用户的需求。

🛠️ **丰富的工具集**：该服务提供了一系列实用的工具函数，如`connect_db`用于建立数据库连接，`query`执行SELECT语句（支持参数化防止SQL注入），`execute`执行写操作（INSERT/UPDATE/DELETE），`list_tables`获取表列表，`describe_table`查看表结构，`show_statement`执行SHOW语句，以及`explain`分析查询性能，全面覆盖数据库操作需求。

🛡️ **安全与性能考量**：指南强调了安全最佳实践，如避免硬编码凭证、使用环境变量、限制用户权限、始终使用参数化查询防止SQL注入。在性能优化方面，建议调整连接池参数，使用索引，避免SELECT *，并利用`explain`工具分析慢查询。

💡 **高级功能与支持**：MCP MySQL Server支持通过`execute`工具间接实现事务操作（START TRANSACTION, COMMIT, ROLLBACK），并提供监控连接池状态的方法。文档还包含了常见问题解答和错误处理指南，确保用户在使用过程中遇到问题时能得到有效解决。

简介

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

地址：github.com/huangfeng19…

安装方法

前提条件

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

安装步骤

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

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

方法2：手动安装

# 创建项目目录mkdir mcp-mysql-server && cd mcp-mysql-server# 初始化项目npm init -y# 安装依赖npm install @fhuang/mcp-mysql-server

配置指南

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

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

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

方式2：使用环境变量

创建.env文件：

MYSQL_HOST=localhostMYSQL_USER=your_usernameMYSQL_PASSWORD=your_passwordMYSQL_DATABASE=your_databaseMYSQL_PORT=3306# 连接池配置CONNECTION_LIMIT=10QUEUE_LIMIT=0

然后启动服务：

npx @fhuang/mcp-mysql-server

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

{  "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

示例：

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 (可选): 查询参数数组

示例：

// 简单查询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 (可选): 查询参数数组

示例：

// 插入数据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 - 列出所有表

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

参数： 无

示例：

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

5. describe_table - 查看表结构

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

参数：

table: 表名

示例：

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

6. show_statement - 执行SHOW语句

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

参数：

sql: SHOW语句

示例：

// 查看数据库参数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语句

示例：

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可能原因: 缺少必填参数、参数类型错误解决方法: 检查参数是否完整、验证参数类型

性能优化

连接池配置

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

# 最大连接数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: 服务启动后无法连接到数据库，如何排查？

A:

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

高级功能

事务支持

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

// 开始事务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"  }});

监控连接池状态

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

总结

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

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