Skip to main content
Glama
mcp-mysql-server

mcp-mysql-server

by 81832310

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 build

2. 配置数据库连接

创建 ~/.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 个工具一览

工具

用途

list_profiles

列出所有数据库配置(脱敏,不含密码)

use_profile

切换数据库连接(验证连通性后才切换)

current_profile

查看当前使用的数据库连接

query

执行 SQL(受安全策略控制)

list_databases

列出可访问的数据库

list_tables

列出表及行数、引擎、注释

describe_table

查看字段定义和索引

explain_query

执行计划分析 + 优化建议

generate_schema_doc

生成 Markdown 表结构文档

analyze_relations

分析表间关系(外键 + 索引推断)

table_stats

表数据量、存储大小、更新时间

所有数据工具支持可选的 profile 参数,临时使用其他环境查询而不切换当前连接。

配置详解

Profiles 文件(推荐)

路径:~/.mcp-mysql/profiles.yml,可通过 MYSQL_PROFILES_FILE 环境变量覆盖。

每个 profile 可单独设置:

字段

默认值

说明

host

—

必填,数据库地址

port

3306

端口

user

—

必填,用户名

password

—

必填,密码

database

—

默认数据库

readonly

true

只读模式

allowDdl

false

允许 DDL(需 readonly=false)

maxRows

1000

查询最大返回行数

queryTimeout

30000

查询超时(毫秒)

poolSize

5

连接池大小

安全建议:

  • 不要将 profiles.yml 提交到代码仓库

  • Unix/macOS:chmod 600 ~/.mcp-mysql/profiles.yml

  • Windows:通过文件属性限制访问权限

环境变量

没有 profiles.yml 时回退到环境变量:

变量

必填

默认值

说明

MYSQL_HOST

是

127.0.0.1

数据库地址

MYSQL_PORT

否

3306

端口

MYSQL_USER

是

—

用户名

MYSQL_PASSWORD

是

—

密码

MYSQL_DATABASE

否

—

默认数据库

MYSQL_DSN

否

—

连接串 mysql://user:pass@host:port/db,与上面互斥

READONLY

否

true

只读模式

ALLOW_DDL

否

false

允许 DDL

MAX_ROWS

否

1000

最大返回行数

QUERY_TIMEOUT

否

30000

超时毫秒

POOL_SIZE

否

5

连接池大小

优先级:profiles.yml > 环境变量 > DSN。

安全模式

模式

配置

允许的 SQL

只读(默认)

readonly: true

SELECT, SHOW, DESCRIBE, EXPLAIN

DML

readonly: false

上述 + INSERT, UPDATE, DELETE

DDL

readonly: false + allowDdl: true

全部

额外保护:

  • 禁止多语句执行(; 分隔的多条语句会被拦截)

  • 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 tools
analyze_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

    A3.7/5.0

    Scored across 11 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose: profile management, querying, schema exploration, documentation generation, relationship analysis, and statistics. No two tools overlap in functionality.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      A
      quality
      B
      maintenance
      Enables Claude Desktop to execute read-only SQL queries on MySQL databases via natural language, with dynamic connection switching and built-in security.
      3
      224 npm
      7
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude AI to execute MySQL queries, list tables, and describe table structures through natural language, with support for parameterized queries and connection pooling.
      ISC