Which integrations are available for this server?

Provides tools for interacting with MariaDB databases, enabling querying, writing, schema exploration, and administration tasks. Provides tools for interacting with MySQL databases, enabling querying, writing, schema exploration, and administration tasks.

How do I use MySQL MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MySQL MCP Server describe the users table" 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.

MySQL MCP Server

by yclenove

Overview Schema Related Servers Score Discussions

TypeScript

Remote

MySQL MCP Server

npm version License: MIT Node.js

简体中文 | English

基于 MCP（Model Context Protocol）的 MySQL 数据库工具服务，供 Claude / Cursor 等客户端通过 stdio 安全地查询与（可选）写入数据。

特性概览

工具：核心约 20+ 个 MCP 工具；另可按环境变量启用多连接、运维、慢日志尾部等（见工具一览）。
安全：参数化查询；DELETE/UPDATE 须带 WHERE；拦截 TRUNCATE / DROP / ALTER；可选库白名单 MYSQL_DATABASE_ALLOWLIST。
只读模式：MYSQL_READONLY=true 时工具层 + 会话层 transaction_read_only 双保险。
多 DSN：MYSQL_MCP_EXTRA_CONNECTIONS + list_connections / use_connection。
EXPLAIN：行式计划 + 中文告警；可选 MYSQL_MCP_EXPLAIN_JSON 解析 FORMAT=JSON。
Token：schema/overview 可限制展开表数；MCP_QUERY_RESULT_HINT 可返回结果近似字符数。
审计 / 运维：可选审计日志、进程列表、慢查询变量、慢日志文件尾部等（均需显式开关）。
资源与提示：4 类 Resource、4 个 Prompt；详见下文。

架构

MCP Client (Claude / Cursor)
    │  stdio JSON-RPC
    ▼
MCP Server (server.ts)
    ├── Query ───────────── query, explain_query
    ├── Modify ──────────── insert, update, delete, call_procedure
    ├── Schema ──────────── test_connection, use_database, show_databases,
    │                        list_tables, describe_table, show_indexes, show_create_table
    ├── Connections ─────── list_connections, use_connection
    ├── Ops（可选）──────── process_list, slow_query_status, kill_query,
    │                        read_audit_log, read_slow_query_log
    ├── Batch ───────────── batch_execute, batch_insert
    ├── DDL ─────────────── create_table
    ├── Resources ───────── schema/overview, schema/table/{name},
    │                      databases, status/pool
    └── Prompts ─────────── analyze-table, generate-query, optimize-query, data-overview
    ▼
Executor (executor.ts) ← 超时 / 重试 / 危险语句 / 审计
    ▼
Connection Pool (connection.ts) ← 多池、只读会话、mysql2
    ▼
MySQL / MariaDB

快速开始

npx（推荐）

npx -y @yclenove/mysql-mcp-server

全局安装

npm install -g @yclenove/mysql-mcp-server
mysql-mcp-server

从源码

git clone https://github.com/yclenove/mysql-mcp-server.git
cd mysql-mcp-server
npm install
npm run build
npm start

自行发布 / 换包名

包名由 package.json 的 name 决定（当前为 @yclenove/mysql-mcp-server）。发布需对应 npm 作用域权限；换用户名请改 name 后 npm publish --access public，客户端 npx 参数需同步。

GitHub Actions 发布（避免 npm error code EOTP）：若开启 2FA，请在 npm 创建 Granular 或 Automation 类 token，写入仓库 Secret NPM_TOKEN。详见 .github/workflows/publish.yml 顶部注释。

工具一览

查询与分析

工具	说明	参数
`query`	只读 SELECT/SHOW/DESCRIBE/EXPLAIN；? 占位；`limit` 或 `page`+`pageSize`	`sql`, `params?`, `limit?`, `page?`, `pageSize?`
`explain_query`	执行计划；默认行式 EXPLAIN + 告警；`MYSQL_MCP_EXPLAIN_JSON=true` 时用 FORMAT=JSON	`sql`

元数据与连接

工具	说明	参数
`test_connection`	Ping、version、当前 `connectionId` / database	无
`use_database`	`USE` 切换库（受白名单约束）	`database`
`show_databases`	列出库（受白名单过滤）	无
`list_tables`	表列表与元数据	`database?`
`describe_table`	列结构	`table`
`show_indexes`	索引	`table`
`show_create_table`	建表语句	`table`
`list_connections`	已配置连接 id / host / port / database（无密码）	无
`use_connection`	切换活动连接	`connection_id`

写入与批量

工具	说明	参数
`insert` / `update` / `delete`	参数化；UPDATE/DELETE 必须含 WHERE	`sql`, `params?`
`call_procedure`	存储过程	`procedure`, `params?`
`batch_execute`	事务批量，最多 50 条	`statements[]`
`batch_insert`	批量插入，最多 50 行	`table`, `records[]`
`create_table`	建表（只读模式禁用）	`table`, `columns[]`, …

可选运维（需环境变量）

工具	前置条件
`process_list`	`MYSQL_MCP_OPS_TOOLS=true`；行数上限 `MYSQL_MCP_PROCESS_LIST_MAX`
`slow_query_status`	`MYSQL_MCP_OPS_TOOLS=true`
`kill_query`	`MYSQL_MCP_KILL_QUERY=true`；`MYSQL_READONLY` 时不可用
`read_audit_log`	`MYSQL_MCP_READ_AUDIT_TOOL=true` 且已设 `MCP_AUDIT_LOG`
`read_slow_query_log`	`MYSQL_MCP_READ_SLOW_LOG=true` 且已设 `MYSQL_MCP_SLOW_LOG_PATH`

Resources 与 Prompts

MCP Resources

资源 URI	说明
`mysql://schema/overview`	当前库表与列摘要；大库可限制展开表数 `MCP_SCHEMA_OVERVIEW_MAX_TABLES`
`mysql://schema/table/{tableName}`	单表列 JSON
`mysql://databases`	库名 JSON 数组（受白名单过滤）
`mysql://status/pool`	连接池状态

MCP Prompts

Prompt	说明
`analyze-table`	表结构 / 索引 / 行数分析
`generate-query`	自然语言 → 参数化 SELECT + `query`
`optimize-query`	EXPLAIN + 索引与改写建议
`data-overview`	库级概览

手动验收清单见 MCP_CURSOR_TEST.md。

安全与只读

参数化：所有工具使用参数化执行，防止 SQL 注入。
危险语句：DELETE/UPDATE 须含 WHERE；TRUNCATE / DROP / ALTER 拦截。
只读模式 MYSQL_READONLY=true：
1. 写入类工具拒绝；
2. 批量中非只读语句拒绝；
3. 执行层校验；
4. 新建池连接执行 SET SESSION transaction_read_only = 1（MySQL 5.6+ / MariaDB 10.0+；仅会话级，与全局 read_only 无关）。

配置说明

在项目根目录放置 .env（可复制 .env.example），启动时自动加载；勿提交 .env。自 v1.4.2 起：若该文件存在，其中出现的键会覆盖进程已继承的环境变量（含系统里的 MYSQL_*）；若未找到项目 .env，则仍仅使用环境变量与默认行为。

连接与账号

变量	默认值	说明
`MYSQL_HOST`	localhost	主机
`MYSQL_PORT`	3306	端口
`MYSQL_USER`	root	用户
`MYSQL_PASSWORD`	-	密码
`MYSQL_DATABASE`	-	默认库
`MYSQL_URL` / `MYSQL_CONNECTION_STRING`	-	`mysql://` 或 `mysql2://`；与分项二选一；密码请 URL 编码

安全与白名单

变量	说明
`MYSQL_DATABASE_ALLOWLIST`	逗号分隔库名；影响启动校验、`use_database`、`list_tables`（指定库）、`show_databases`、Resource `mysql://databases`
`MYSQL_MCP_VALIDATE_EXTRA_CONNECTIONS`	`true` 且已设白名单时，校验每个额外 DSN 的默认库
`MYSQL_MAX_SQL_LENGTH`	单条 SQL 最大字符数（默认 102400）

执行与连接池

变量	默认值	说明
`MYSQL_MAX_ROWS`	100	单次最大返回行数
`MYSQL_QUERY_TIMEOUT`	30000	查询超时（毫秒）
`MYSQL_RETRY_COUNT`	2	只读重试次数
`MYSQL_RETRY_DELAY_MS`	200	重试退避基数
`MYSQL_CONNECTION_LIMIT`	10	连接池大小
`MYSQL_TIMEOUT`	60000	连接超时（毫秒）
`MYSQL_SSL_CA` / `SSL_CERT` / `SSL_KEY`	-	SSL

只读、调试与 MCP

变量	说明
`MYSQL_READONLY`	`true` 只读模式
`MCP_DEBUG`	`true` 时工具返回 `executionTime`
`MCP_SCHEMA_OVERVIEW_MAX_TABLES`	默认 50；`0` 仅表名；Resource `schema/overview`
`MCP_AUDIT_LOG`	审计日志文件路径
`MCP_QUERY_RESULT_HINT`	`true` 时 `query` 返回 `approxChars`
`MYSQL_MCP_EXPLAIN_JSON`	`true` 时 `explain_query` 使用 `EXPLAIN FORMAT=JSON`

多 DSN

变量	说明
`MYSQL_MCP_EXTRA_CONNECTIONS`	JSON 数组，如 `[{"id":"replica","url":"mysql://..."}]`
`MYSQL_MCP_CONNECTION_ID`	当前活动连接 id，默认 `default`

运维（可选）

变量	说明
`MYSQL_MCP_OPS_TOOLS`	`true` → `process_list`、`slow_query_status`
`MYSQL_MCP_PROCESS_LIST_MAX`	`process_list` 最大行数（默认 100，上限 5000）
`MYSQL_MCP_KILL_QUERY`	`true` → `kill_query`
`MYSQL_MCP_READ_AUDIT_TOOL`	`true` 且已设 `MCP_AUDIT_LOG` → `read_audit_log`
`MYSQL_MCP_READ_SLOW_LOG`	`true` 且已设 `MYSQL_MCP_SLOW_LOG_PATH` → `read_slow_query_log`
`MYSQL_MCP_SLOW_LOG_PATH`	慢查询日志文件路径（进程需可读）

客户端接入

Claude Desktop

编辑 claude_desktop_config.json（[macOS] ~/Library/Application Support/Claude/、[Windows] %APPDATA%/Claude/）：

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

Cursor

Add to Cursor

打开本仓库为工作区根目录（使进程 cwd 能加载项目根下的 .env；多文件夹工作区时请单独打开本仓库或将其设为根）。
安装 npm 包（全局）：npm install -g @yclenove/mysql-mcp-server@latest，确保终端里能执行 mysql-mcp-server（Windows 需保证 Node 的 npm 全局 bin 在 PATH 中）。
连接信息：写在项目根目录 .env（已在 .gitignore，勿提交密码）。不要在 MCP 配置的 env 里写生产密码；本地可空 env、仅依赖 .env。
Cursor MCP 配置：本仓库不提交 .cursor/。请在 Cursor 设置中新增 MCP，或在本机创建项目根 .cursor/mcp.json（仅本地，勿提交），使用 mysql-mcp-server（无额外 args）。保存后可在 Cursor → Settings → MCP 中启用 mysql-mcp，或重载窗口。
环境变量优先级（v1.4.2+）：若项目根存在 .env，其中出现的 MYSQL_* 等会覆盖你系统中已设置的同名变量，避免误连 127.0.0.1。若要用系统环境覆盖 .env，需临时重命名或移走项目 .env。
全功能手动测试见 MCP_CURSOR_TEST.md。

示例（自行保存为本地 .cursor/mcp.json，勿提交）：

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "mysql-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

不装全局时可用 npx："command": "npx"，"args": ["-y", "@yclenove/mysql-mcp-server"]。
本地改源码调试时，可把 command / args 改回 node + ${workspaceFolder}/dist/index.js（需先 npm run build）。

生产只读示例

{
  "mcpServers": {
    "mysql-prod": {
      "command": "npx",
      "args": ["-y", "@yclenove/mysql-mcp-server"],
      "env": {
        "MYSQL_HOST": "prod-db.example.com",
        "MYSQL_USER": "readonly_user",
        "MYSQL_PASSWORD": "password",
        "MYSQL_DATABASE": "production",
        "MYSQL_READONLY": "true"
      }
    }
  }
}

本地开发与本仓库调试

安装与编译
```
npm install
npm run build
```
方式 A：全局 mysql-mcp-server（与 npm 一致）
全局安装后，在本地自建的 .cursor/mcp.json（不提交）中配置 command: "mysql-mcp-server"。打开本仓库根目录后重载 MCP；连接信息仍读项目根 .env。
方式 B：调试当前仓库构建产物
在本机 MCP 配置中改为 node + ${workspaceFolder}/dist/index.js，执行 npm run build 后重载 MCP，无需发布到 npm。
验证
在 Cursor 中启用 MCP 后，按 MCP_CURSOR_TEST.md 逐项调用工具；或执行 npm test、npm run inspector 调试。

开发与构建

扩展工具 / Resource / Prompt 前请阅读 AGENTS.md（token 与描述约定）。

目录结构（节选）

src/
├── index.ts           # 入口，加载 .env
├── server.ts          # MCP Server 注册
├── resources.ts       # Resources
├── prompts.ts         # Prompts
├── audit.ts
├── explainWarnings.ts
├── schemaOverviewLimit.ts
├── db/
│   ├── connection.ts  # 多池、只读会话、配置
│   ├── executor.ts
│   └── allowlist.ts
└── tools/
    ├── query.ts
    ├── modify.ts
    ├── schema.ts
    ├── connections.ts
    ├── ops.ts
    ├── batch.ts
    └── ddl.ts
test/                    # *.test.mjs

常用命令

npm run dev        # tsc --watch
npm run build        # 编译
npm start            # 启动 MCP
npm test             # 单元测试
npm run lint
npm run format
npm run format:check
npm run inspector    # MCP Inspector

Docker

docker build -t mysql-mcp-server .
docker run -e MYSQL_HOST=host.docker.internal \
           -e MYSQL_USER=root \
           -e MYSQL_PASSWORD=password \
           -e MYSQL_DATABASE=mydb \
           mysql-mcp-server

故障排查

现象	处理
连接失败	检查 MySQL 与 `host/port/user/password`；远程注意防火墙与 `bind-address`
日志已写「Loading .env from: …\.env」，但下一行 `MySQL:` 仍是 `127.0.0.1` 等错误地址	v1.4.2+：项目 `.env` 会覆盖系统里同名 `MYSQL_*`。若仍为旧行为，请升级依赖；或检查 `.env` 内是否缺少 `MYSQL_HOST`
查询超时	增大 `MYSQL_QUERY_TIMEOUT`；大结果配合 `MYSQL_MAX_ROWS`
只读下写入报错	预期行为；检查 `MYSQL_READONLY`
SSL	设置 `MYSQL_SSL_CA` 等
MCP 未加载本地构建	确认已 `npm run build`，工作区根为本仓库，且 MCP 配置中 `node` 路径指向 `dist/index.js`

更新日志

详见 CHANGELOG.md。

License

MIT

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

0dRelease cycle

6Releases (12mo)

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/yclenove/mysql-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server