lzc-mysql-mcp

v2.0.0

Published

13 days ago

A read-only MCP server for querying MySQL databases via stdio transport (multi-database support)

0High
0Medium
0Low

leo_666

mcp mysql query read-only multi-database ai claude codex

MySQL MCP Server

一个基于 stdio 传输的 MCP (Model Context Protocol) 服务器，让 AI Agent 安全地查询 MySQL 数据库。支持多数据源、自定义表描述提示词，所有查询均为只读。

一行命令即可使用，无需下载源码：

npx lzc-mysql-mcp

功能特性

| 特性 | 说明 | |------|------| | 零安装使用 | npx lzc-mysql-mcp 直接运行，无需 clone / build | | 多数据源 | 一个配置文件同时连接多个 MySQL 数据库，工具通过 database 参数切换 | | 自定义提示词 | 为每个库和表编写业务描述，AI 在对话时自动感知数据含义 | | 灵活配置 | 支持项目级配置 (./mysql-config.json)、全局配置 (~/.mysql-mcp/config.json)、环境变量 | | 安全只读 | 仅允许 SELECT / SHOW / DESCRIBE / EXPLAIN，从协议层杜绝写操作 | | 自动 LIMIT | SELECT 未指定 LIMIT 时自动追加，防止返回海量数据 | | 查询超时 | 通过 MySQL MAX_EXECUTION_TIME 控制执行时间 | | Markdown 表格 | 查询结果格式化为易读的 Markdown 表格 | | 连接池 | 每个数据源独立连接池 (mysql2)，最大 5 并发 |

快速开始

前置条件

Node.js >= 18
MySQL 5.7+
Windows / macOS / Linux 均可

第一步: 创建配置文件

选择以下任一位置放置配置文件（服务器按优先级依次查找）：

| 优先级 | 位置 | 适用场景 | |--------|------|---------| | 1 | 项目目录 ./mysql-config.json | 项目级配置，每个项目不同数据库 | | 2 | 全局目录 ~/.mysql-mcp/config.json | 所有项目共用一套数据库配置 | | 3 | 环境变量 MYSQL_DATABASE 等 | 快速单库模式，无需 JSON 文件 |

推荐做法: 创建全局配置，一次配置到处使用：

# macOS/Linux
mkdir -p ~/.mysql-mcp
cp mysql-config.example.json ~/.mysql-mcp/config.json

# Windows (PowerShell)
mkdir "$env:USERPROFILE\.mysql-mcp"
copy mysql-config.example.json "$env:USERPROFILE\.mysql-mcp\config.json"

然后编辑 ~/.mysql-mcp/config.json 填入你的 MySQL 连接信息。

第二步: 运行

npx lzc-mysql-mcp

看到以下输出即表示成功：

[mysql-mcp] 使用配置文件: /Users/xxx/.mysql-mcp/config.json
[mysql-mcp] 已连接 MySQL 8.0.x @ 127.0.0.1:3306, 数据库: big_market
[mysql-mcp] 共 1 个数据源已就绪, 默认数据库: big_market
[mysql-mcp] Server 已启动 (stdio 模式)

npx 会自动从 npm 下载并运行，无需手动 clone 或 build。

配置说明

配置文件查找优先级

服务器启动时，按以下顺序查找配置：

1. MYSQL_CONFIG_FILE 环境变量 → 使用指定路径
2. ./mysql-config.json        → 当前工作目录下的配置
3. ~/.mysql-mcp/config.json   → 用户主目录下的全局配置
4. MYSQL_DATABASE 环境变量    → 单库模式 (向后兼容)

完整配置示例

{
  "defaultDatabase": "big_market",
  "maxRows": 1000,
  "queryTimeout": 30000,
  "connections": [
    {
      "host": "127.0.0.1",
      "port": 3306,
      "user": "root",
      "password": "your_password",
      "database": "big_market",
      "description": "大营销平台核心库，包含用户、活动、账户等核心业务表"
    },
    {
      "host": "192.168.1.100",
      "port": 3306,
      "user": "readonly",
      "password": "your_password",
      "database": "demo",
      "description": "演示库，包含测试数据"
    }
  ],
  "tableHints": {
    "big_market": {
      "user": "用户表，存储注册用户信息",
      "raffle_activity": "抽奖活动表，定义活动的规则与配置",
      "raffle_activity_account": "活动账户表，每个用户在每个活动下的账户额度"
    },
    "demo": {
      "orders": "订单表，记录所有用户订单"
    }
  }
}

字段说明

| 字段 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | defaultDatabase | string | 否 | 第一个 connection 的 database | 不传 database 参数时使用的默认库 | | maxRows | number | 否 | 100 | 查询结果最大行数限制 | | queryTimeout | number | 否 | 30000 | 查询超时时间 (毫秒) | | connections | array | 是 | — | 数据库连接列表，至少配置一个 | | connections[].host | string | 是 | — | MySQL 主机地址 | | connections[].port | number | 是 | — | MySQL 端口 | | connections[].user | string | 是 | — | MySQL 用户名 | | connections[].password | string | 是 | — | MySQL 密码 | | connections[].database | string | 是 | — | 数据库名 (必须全局唯一) | | connections[].description | string | 否 | — | 数据库的业务描述，AI 可自动感知 | | tableHints | object | 否 | — | 按数据库名分组，为每个表配置业务描述 | | tableHints.<db>.<table> | string | 否 | — | 表的业务含义描述 |

单库模式 (环境变量)

如果不需要多库，也可以直接用环境变量：

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database
MYSQL_MAX_ROWS=100
MYSQL_QUERY_TIMEOUT=30000

集成到 AI 客户端

有两种使用方式，选择其中一种即可：

| 方式 | 说明 | 适用场景 | |------|------|---------| | npm 方式 | npx lzc-mysql-mcp 直接运行 | 已发布到 npm，最省心 | | 本地路径方式 | node /your/path/dist/index.js | 未发布 npm，或自己 clone 了源码 |

下方每个客户端都给出了两种方式的配置，按需选择。

1. Claude Code

Claude Code 通过命令行注册 MCP 服务器。

npm 方式

# 全局注册 (所有项目可用)
claude mcp add mysql -- npx -y lzc-mysql-mcp

# 仅当前项目生效
claude mcp add --scope project mysql -- npx -y lzc-mysql-mcp

本地路径方式

# Windows
claude mcp add mysql -- node C:/Users/Administrator/Desktop/lzc/mysql-mcp/dist/index.js

# macOS/Linux
claude mcp add mysql -- node /Users/yourname/projects/mysql-mcp/dist/index.js

指定配置文件路径

claude mcp add mysql \
  -e MYSQL_CONFIG_FILE=/path/to/your/config.json \
  -- npx -y lzc-mysql-mcp

使用环境变量单库模式 (无需 JSON 文件)

claude mcp add mysql \
  -e MYSQL_HOST=127.0.0.1 \
  -e MYSQL_PORT=3306 \
  -e MYSQL_USER=root \
  -e MYSQL_PASSWORD=your_password \
  -e MYSQL_DATABASE=your_database \
  -- npx -y lzc-mysql-mcp

验证与删除

# 查看已注册的 MCP 服务器
claude mcp list

# 删除注册
claude mcp remove mysql

2. OpenAI Codex

Codex 通过 ~/.codex/config.toml (全局) 或项目下 .codex/config.toml 配置。

npm 方式

编辑 ~/.codex/config.toml，追加：

[mcp_servers.mysql]
command = "npx"
args = ["-y", "lzc-mysql-mcp"]

本地路径方式

# Windows
[mcp_servers.mysql]
command = "node"
args = ["C:/Users/Administrator/Desktop/lzc/mysql-mcp/dist/index.js"]

# macOS/Linux
[mcp_servers.mysql]
command = "node"
args = ["/Users/yourname/projects/mysql-mcp/dist/index.js"]

指定配置文件

[mcp_servers.mysql]
command = "npx"
args = ["-y", "lzc-mysql-mcp"]

[mcp_servers.mysql.env]
MYSQL_CONFIG_FILE = "/Users/yourname/.mysql-mcp/config.json"

macOS/Linux 一键追加

mkdir -p ~/.codex && cat >> ~/.codex/config.toml << 'EOF'

[mcp_servers.mysql]
command = "npx"
args = ["-y", "lzc-mysql-mcp"]
EOF

Windows PowerShell 一键追加

Add-Content -Path "$env:USERPROFILE\.codex\config.toml" -Value @'

[mcp_servers.mysql]
command = "npx"
args = ["-y", "lzc-mysql-mcp"]
'@

3. Claude Desktop

编辑配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

npm 方式

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "lzc-mysql-mcp"]
    }
  }
}

本地路径方式

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["C:/Users/Administrator/Desktop/lzc/mysql-mcp/dist/index.js"]
    }
  }
}

指定配置文件

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "lzc-mysql-mcp"],
      "env": {
        "MYSQL_CONFIG_FILE": "C:/Users/Administrator/.mysql-mcp/config.json"
      }
    }
  }
}

4. Cursor

编辑项目下的 .cursor/mcp.json：

npm 方式

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "lzc-mysql-mcp"]
    }
  }
}

本地路径方式

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["C:/Users/Administrator/Desktop/lzc/mysql-mcp/dist/index.js"]
    }
  }
}

指定配置文件

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "lzc-mysql-mcp"],
      "env": {
        "MYSQL_CONFIG_FILE": "C:/Users/Administrator/.mysql-mcp/config.json"
      }
    }
  }
}

5. Windsurf

编辑 Windsurf 配置文件 (通常在 ~/.windsurf/settings.json 或项目下 .windsurfrc)：

npm 方式

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "lzc-mysql-mcp"]
    }
  }
}

本地路径方式

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["C:/Users/Administrator/Desktop/lzc/mysql-mcp/dist/index.js"]
    }
  }
}

配置方式速查表

| 客户端 | npm 方式 command | 本地方式 command | 本地方式 args 示例 | |--------|-----------------|-----------------|-------------------| | Claude Code | npx -y lzc-mysql-mcp | node .../dist/index.js | — | | OpenAI Codex | npx + ["-y", "lzc-mysql-mcp"] | node + [".../dist/index.js"] | 见上方 | | Claude Desktop | npx + ["-y", "lzc-mysql-mcp"] | node + [".../dist/index.js"] | 见上方 | | Cursor | npx + ["-y", "lzc-mysql-mcp"] | node + [".../dist/index.js"] | 见上方 | | Windsurf | npx + ["-y", "lzc-mysql-mcp"] | node + [".../dist/index.js"] | 见上方 |

工具列表

| 工具名称 | 说明 | database 参数 | |---------|------|:---:| | list_all_connections | 列出所有已配置的数据源及其描述 | - | | get_table_hint | 获取表的业务描述 (配置 + MySQL COMMENT) | 可选 | | query | 执行自定义只读 SQL 查询 | 可选 | | list_databases | 列出 MySQL 实例上所有可访问的数据库 | - | | list_tables | 列出指定数据库的所有表及其大小、行数等信息 | 可选 | | describe_table | 查看指定表的完整字段结构 | 可选 | | show_create_table | 查看指定表的 CREATE TABLE DDL | 可选 | | show_indexes | 查看指定表的所有索引信息 | 可选 | | show_table_sample | 查看指定表的样本数据 | 可选 | | explain_query | 分析 SELECT 查询的执行计划 | 可选 | | show_table_row_count | 精确统计指定表的行数 | 可选 | | search_tables | 根据关键字模糊搜索表名或表注释 | 可选 |

标记"可选"的 database 参数：不传则使用 defaultDatabase。

工具详细说明

`list_all_connections`

列出配置文件中定义的所有数据源，包含连接地址、是否为默认库、业务描述。

参数: 无

示例返回:

已配置 2 个数据源:
  1. [email protected]:3306 (默认) — 大营销平台核心库
  2. [email protected]:3306 — 演示库

默认数据库: big_market

`get_table_hint`

合并返回三个来源的表描述信息：

配置文件 tableHints 中的自定义描述
MySQL TABLE_COMMENT (建表时的注释)
MySQL COLUMN_COMMENT (列注释)

参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | table | string | 是 | 表名 | | database | string | 否 | 数据库名，默认使用 defaultDatabase |

`query`

执行任意只读 SQL 语句。

参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | sql | string | 是 | SQL 查询语句 (仅允许只读) | | database | string | 否 | 数据库名，默认使用 defaultDatabase | | max_rows | number | 否 | 最大返回行数，默认取配置中的 maxRows |

`list_databases`

列出 MySQL 实例上当前用户可访问的所有数据库。

参数: 无

`list_tables`

列出指定数据库中的所有表，返回：表名、预估行数、数据大小 (KB)、索引大小 (KB)、表注释、存储引擎、创建时间、更新时间。

参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | database | string | 否 | 数据库名 |

`describe_table`

查看指定表的完整字段定义：字段名、类型、是否可空、键类型、默认值、额外属性、注释。

参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | table | string | 是 | 表名 | | database | string | 否 | 数据库名 |

`show_create_table`

返回指定表的完整 CREATE TABLE DDL，包含列定义、索引、约束、字符集等。

参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | table | string | 是 | 表名 | | database | string | 否 | 数据库名 |

`show_indexes`

查看指定表的所有索引信息。

参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | table | string | 是 | 表名 | | database | string | 否 | 数据库名 |

`show_table_sample`

快速预览表中的数据内容。

参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | table | string | 是 | 表名 | | database | string | 否 | 数据库名 | | limit | number | 否 | 返回行数，默认 10 | | order_by | string | 否 | 排序方式，如 "id DESC" |

`explain_query`

分析 SELECT 查询的执行计划。

参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | sql | string | 是 | 要分析的 SELECT 语句 | | database | string | 否 | 数据库名 |

`show_table_row_count`

使用 COUNT(*) 精确统计表的行数。

参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | table | string | 是 | 表名 | | database | string | 否 | 数据库名 | | where | string | 否 | WHERE 条件，如 "status = 1" |

`search_tables`

根据关键字模糊搜索匹配的表名或表注释。

参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | keyword | string | 是 | 搜索关键字 | | database | string | 否 | 数据库名 |

跨平台说明

本项目 完全跨平台兼容 (Windows / macOS / Linux)：

所有路径使用 path.resolve() / path.join() 处理，自动适配 / 和 \
所有依赖均为纯 JavaScript 包，不含原生二进制模块
#!/usr/bin/env node 在 macOS/Linux 上作为 shebang，在 Windows 上被忽略
npx 在所有平台上行为一致

配置文件路径说明

~ 表示用户主目录：

macOS/Linux: /Users/yourname 或 /home/yourname
Windows: C:\Users\Administrator (即 %USERPROFILE%)

全局配置 ~/.mysql-mcp/config.json 在所有平台上都能被正确识别。

安全机制

| 机制 | 说明 | |------|------| | SQL 类型白名单 | 只有 SELECT / SHOW / DESCRIBE / EXPLAIN 开头的语句才执行 | | 表名校验 | 表名参数仅允许 [a-zA-Z0-9_] | | 自动 LIMIT | SELECT 无 LIMIT 时自动追加，防止内存溢出 | | 查询超时 | 通过 MAX_EXECUTION_TIME 限制执行时间 | | 连接池限制 | 每个数据源最大 5 个并发连接 | | 只读用户建议 | 建议配置 MySQL 只读用户，最小权限原则 |

典型使用场景

Agent 工作流:

1. list_all_connections    → 了解有哪些数据库
2. search_tables           → 搜索与 "order" 相关的表
3. get_table_hint          → 了解表的业务含义
4. describe_table          → 查看表结构
5. show_table_sample       → 预览数据
6. explain_query           → 分析执行计划
7. query                   → 执行最终查询 (可指定不同数据库)

项目结构

mysql-mcp/
├── src/
│   └── index.ts                   # MCP Server 主程序
├── dist/                          # 编译输出
│   └── index.js
├── mysql-config.example.json      # JSON 配置模板
├── package.json
├── tsconfig.json
└── README.md

发布到 npm (开发者)

如果你 fork 了本项目并想发布到 npm：

# 1. 编译
npm run build

# 2. 登录 npm
npm login

# 3. 发布
npm publish

package.json 中已配置：

"bin": { "lzc-mysql-mcp": "dist/index.js" } — 注册全局命令
"files": ["dist"] — 只发布编译产物，不发布源码
"prepublishOnly": "npm run build" — 发布前自动编译

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

MySQL MCP Server

目录

功能特性

快速开始

前置条件

第一步: 创建配置文件

第二步: 运行

配置说明

配置文件查找优先级

完整配置示例

字段说明

单库模式 (环境变量)

集成到 AI 客户端

1. Claude Code

npm 方式

本地路径方式

指定配置文件路径

使用环境变量单库模式 (无需 JSON 文件)

验证与删除

2. OpenAI Codex

npm 方式

本地路径方式

指定配置文件

macOS/Linux 一键追加

Windows PowerShell 一键追加

3. Claude Desktop

npm 方式

本地路径方式

指定配置文件

4. Cursor

npm 方式

本地路径方式

指定配置文件

5. Windsurf

npm 方式

本地路径方式

配置方式速查表

工具列表

工具详细说明

list_all_connections

get_table_hint

query

list_databases

list_tables

describe_table

show_create_table

show_indexes

show_table_sample

explain_query

show_table_row_count

search_tables

跨平台说明

配置文件路径说明

安全机制

典型使用场景

项目结构

发布到 npm (开发者)

`list_all_connections`

`get_table_hint`

`query`

`list_databases`

`list_tables`

`describe_table`

`show_create_table`

`show_indexes`

`show_table_sample`

`explain_query`

`show_table_row_count`

`search_tables`