mcp-mysql-server
Enables AI agents to interact with MySQL databases, allowing queries, schema exploration, and management through natural language or structured commands.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-mysql-server list tables in my_app database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP MySQL Server
基于 @modelcontextprotocol/sdk + mysql2 的 MySQL MCP Server,让 Claude Code 直接操作 MySQL 数据库。
快速开始
1. 安装
git clone <repo-url> && cd mcp-mysql-server
npm install && npm run build2. 配置数据库连接
创建 ~/.mcp-mysql/profiles.yml(推荐,支持多环境切换):
default: dev
profiles:
dev:
host: 127.0.0.1
port: 3306
user: root
password: "your_password"
database: my_app
readonly: true
staging:
host: 192.168.1.100
user: readonly
password: "staging_password"
database: my_app没有 profiles.yml 时,可通过环境变量
MYSQL_HOST/MYSQL_USER/MYSQL_PASSWORD/MYSQL_DATABASE配置单连接。
3. 注册到 Claude Code
# 用户级别注册(所有项目可用)
claude mcp add mysql node /absolute/path/to/mcp-mysql-server/dist/index.js -s user
# 或使用 npx(已发布到 npm 时)
claude mcp add mysql npx @huangcaiming5913/mcp-mysql-server -s user也可以手动编辑 ~/.claude/.mcp.json:
{
"mcpServers": {
"mysql": {
"command": "node",
"args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"]
}
}
}4. 开始使用
重启 Claude Code 后,直接用自然语言操作数据库:
> 看下有哪些数据库
> dst_goods 里有什么表
> g_goods_manage 的表结构
> 查一下上架中的商品有多少个
> 切换到 staging 环境Related MCP server: MySQL MCP Server
11 个工具一览
工具 | 用途 |
| 列出所有数据库配置(脱敏,不含密码) |
| 切换数据库连接(验证连通性后才切换) |
| 查看当前使用的数据库连接 |
| 执行 SQL(受安全策略控制) |
| 列出可访问的数据库 |
| 列出表及行数、引擎、注释 |
| 查看字段定义和索引 |
| 执行计划分析 + 优化建议 |
| 生成 Markdown 表结构文档 |
| 分析表间关系(外键 + 索引推断) |
| 表数据量、存储大小、更新时间 |
所有数据工具支持可选的 profile 参数,临时使用其他环境查询而不切换当前连接。
配置详解
Profiles 文件(推荐)
路径:~/.mcp-mysql/profiles.yml,可通过 MYSQL_PROFILES_FILE 环境变量覆盖。
每个 profile 可单独设置:
字段 | 默认值 | 说明 |
| — | 必填,数据库地址 |
|
| 端口 |
| — | 必填,用户名 |
| — | 必填,密码 |
| — | 默认数据库 |
|
| 只读模式 |
|
| 允许 DDL(需 readonly=false) |
|
| 查询最大返回行数 |
|
| 查询超时(毫秒) |
|
| 连接池大小 |
安全建议:
不要将 profiles.yml 提交到代码仓库
Unix/macOS:
chmod 600 ~/.mcp-mysql/profiles.ymlWindows:通过文件属性限制访问权限
环境变量
没有 profiles.yml 时回退到环境变量:
变量 | 必填 | 默认值 | 说明 |
| 是 |
| 数据库地址 |
| 否 |
| 端口 |
| 是 | — | 用户名 |
| 是 | — | 密码 |
| 否 | — | 默认数据库 |
| 否 | — | 连接串 |
| 否 |
| 只读模式 |
| 否 |
| 允许 DDL |
| 否 |
| 最大返回行数 |
| 否 |
| 超时毫秒 |
| 否 |
| 连接池大小 |
优先级:profiles.yml > 环境变量 > DSN。
安全模式
模式 | 配置 | 允许的 SQL |
只读(默认) |
| SELECT, SHOW, DESCRIBE, EXPLAIN |
DML |
| 上述 + INSERT, UPDATE, DELETE |
DDL |
| 全部 |
额外保护:
禁止多语句执行(
;分隔的多条语句会被拦截)SELECT 无 LIMIT 时自动追加
LIMIT {maxRows}
使用示例
# 数据探索
> 看下 dst_goods 数据库有哪些表
> g_goods_manage 的表结构是什么样的
> 查一下上架中的商品有多少个
# 性能分析
> 分析一下这条 SQL 的执行计划:SELECT * FROM g_goods_manage WHERE category_id = 100
# 文档生成
> 帮我生成 g_activity 相关表的表结构文档
# 多环境操作
> 切换到 staging 环境
> 看看哪些表占空间最大
> 用 dev 环境查一下 users 表有多少行(自动使用 profile 参数)项目结构
src/
index.ts # 入口:McpServer + 工具注册 + stdio 传输
config.ts # 配置:profiles.yml + 环境变量 + DSN
connection.ts # MySQL 连接池管理(按 profile 缓存)
registry.ts # 运行时状态:当前 profile + 配置映射
tools/
_common.ts # resolveConn() 按 profile 解析连接
profile.ts # list_profiles / use_profile / current_profile
query.ts # query
schema.ts # list_databases / list_tables / describe_table
explain.ts # explain_query
docs.ts # generate_schema_doc
relations.ts # analyze_relations
stats.ts # table_stats
utils/
sql-guard.ts # SQL 安全校验常见问题
配置修改后不生效? 修改 profiles.yml 中的字段需重启 Claude Code;但切换 profile 不需要重启,用 use_profile 即可。
密码含特殊字符? 用 profiles.yml 或环境变量配置,不要用 DSN(DSN 中特殊字符需 URL 编码)。
如何开启写操作? 设置 readonly: false。DDL 还需 allowDdl: true。生产环境建议保持只读。
如何在多项目中复用? 注册到用户级别(-s user),所有项目可用。也可在项目 .mcp.json 中单独配置不同连接。
Available Tools
11 toolsanalyze_relationsB
Analyze table relationships via foreign keys and indexes
Inputs: profile, database.
current_profileA
Show the current active database profile info
Inputs: no named parameters.
describe_tableA
Show table structure: columns, types, indexes
Inputs: table (required), profile, database.
explain_queryC
Run EXPLAIN on a SELECT query and provide analysis
Inputs: sql (required), profile.
generate_schema_docB
Generate Markdown documentation for database tables
Inputs: tables, profile, database.
list_databasesB
List all accessible databases
Inputs: profile.
list_profilesA
List all available database profiles (passwords hidden)
Inputs: no named parameters.
list_tablesB
List tables in a database with row counts
Inputs: profile, database.
queryC
Execute SQL query (SELECT, SHOW, etc. In readonly mode, only reads are allowed)
Inputs: sql (required), maxRows, profile.
table_statsB
Show table statistics: row counts, data/index sizes, update time
Inputs: table, profile, database.
use_profileA
Switch the current database profile (validates connectivity before switching)
Inputs: name (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Every tool has a clearly distinct purpose: profile management, querying, schema exploration, documentation generation, relationship analysis, and statistics. No two tools overlap in functionality.
Tool names follow a consistent verb_noun (or adjective_noun) pattern using snake_case, with minor exceptions like 'query' that are still intuitive and predictable.
With 11 tools, the set is well-scoped for MySQL database operations, covering profile management, querying, schema exploration, and analysis without being excessive or insufficient.
The tool surface is comprehensive for database introspection and analysis: profile switching, querying, listing databases/tables, describing schemas, explaining queries, generating documentation, analyzing relations, and table stats. No obvious gaps for the intended purpose.
Related MCP Connectors
Hosted MySQL MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted SQL Server MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted PostgreSQL MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Claude Desktop to interact with MySQL databases through secure query execution, schema discovery, and multi-database support with configurable read/write permissions and built-in SQL injection protection.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to securely interact with MySQL databases for schema discovery, data querying, and record management with configurable access controls. It provides specialized tools for listing tables, describing structures, and performing CRUD operations within environments like Claude and VS Code.MIT
- AlicenseAqualityBmaintenanceEnables Claude Desktop to execute read-only SQL queries on MySQL databases via natural language, with dynamic connection switching and built-in security.3224 npm7MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude AI to execute MySQL queries, list tables, and describe table structures through natural language, with support for parameterized queries and connection pooling.ISC