mcp-mysql-hub

中文 | English

一个支持多数据库连接的 MySQL MCP Server，专为 Cursor / Claude Code 设计。
在同一个 AI 会话中自由切换本地、测试、生产等多个 MySQL 环境。

功能特性

• 🔌 多连接管理 — 同时管理多个 MySQL 服务器，按名称自由切换
• 🗄️ 库表浏览 — 列出数据库、表，查看表结构和建表语句
• 🔍 表名搜索 — 按关键词模糊搜索表名
• 📊 数据预览 — 快速查看表的前 N 条数据
• 📝 SQL 执行 — 执行 SELECT 查询和 INSERT / UPDATE 写入
• 🛡️ 安全防护 — 内置拦截 DROP / TRUNCATE / DELETE 等危险操作

可用工具（MCP Tools）

| 工具名 | 说明 | |--------|------| | list_connections | 列出所有已配置的数据库连接 | | list_databases | 列出某个连接上的所有数据库 | | list_tables | 列出某个数据库中的所有表 | | describe_table | 查看表结构（字段、类型、索引、建表语句） | | search_tables | 按关键词搜索表名 | | table_data_preview | 预览表中前 N 条数据 | | run_query | 执行只读 SQL（SELECT / SHOW / DESCRIBE） | | run_write | 执行写入 SQL（INSERT / UPDATE / CREATE） |

前置要求

• Node.js >= 18（运行 node --version 确认）

安装 · Cursor

编辑 ~/.cursor/mcp.json：

• Windows：C:\Users\<用户名>\.cursor\mcp.json
• macOS / Linux：~/.cursor/mcp.json

{
  "mcpServers": {
    "mysql-hub": {
      "command": "npx",
      "args": ["-y", "mcp-mysql-hub"],
      "env": {
        "MYSQL_CONN_1_NAME":     "本地开发",
        "MYSQL_CONN_1_HOST":     "localhost",
        "MYSQL_CONN_1_PORT":     "3306",
        "MYSQL_CONN_1_USER":     "root",
        "MYSQL_CONN_1_PASSWORD": "root",

        "MYSQL_CONN_2_NAME":     "测试服务器",
        "MYSQL_CONN_2_HOST":     "192.168.1.100",
        "MYSQL_CONN_2_PORT":     "3306",
        "MYSQL_CONN_2_USER":     "admin",
        "MYSQL_CONN_2_PASSWORD": "yourpassword"
      }
    }
  }
}

保存后重启 Cursor，MCP 工具列表中即可看到 mysql-hub。

安装 · Claude Code

编辑 ~/.claude/claude_desktop_config.json：

• Windows：C:\Users\<用户名>\.claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mysql-hub": {
      "command": "npx",
      "args": ["-y", "mcp-mysql-hub"],
      "env": {
        "MYSQL_CONN_1_NAME":     "本地开发",
        "MYSQL_CONN_1_HOST":     "localhost",
        "MYSQL_CONN_1_PORT":     "3306",
        "MYSQL_CONN_1_USER":     "root",
        "MYSQL_CONN_1_PASSWORD": "root",

        "MYSQL_CONN_2_NAME":     "测试服务器",
        "MYSQL_CONN_2_HOST":     "192.168.1.100",
        "MYSQL_CONN_2_PORT":     "3306",
        "MYSQL_CONN_2_USER":     "admin",
        "MYSQL_CONN_2_PASSWORD": "yourpassword"
      }
    }
  }
}

保存后重启 Claude Desktop。

连接配置方式

方式一：编号环境变量（推荐）

每个连接的每个字段单独一个环境变量，直接写在配置文件 env 中，无需额外文件。

命名规则：MYSQL_CONN_{序号}_{字段}，序号从 1 开始连续编号。

| 字段 | 必填 | 默认值 | 说明 | |------|:----:|--------|------| | NAME | ✅ | — | 连接名称（调用工具时使用） | | HOST | ✅ | — | 数据库主机地址 | | PORT | ❌ | 3306 | 端口号 | | USER | ✅ | — | 数据库用户名 | | PASSWORD | ✅ | — | 数据库密码 |

方式二：connections.json 文件

在任意目录创建 connections.json，通过 cwd 参数指定文件所在目录：

{
  "本地开发": {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "root"
  },
  "测试服务器": {
    "host": "192.168.1.100",
    "port": 3306,
    "user": "admin",
    "password": "yourpassword"
  }
}

mcp.json / claude_desktop_config.json 中加上 cwd：

{
  "mysql-hub": {
    "command": "npx",
    "args": ["-y", "mcp-mysql-hub"],
    "cwd": "/path/to/folder/with/connections.json"
  }
}

方式三：MYSQL_CONNECTIONS JSON 字符串

"env": {
  "MYSQL_CONNECTIONS": "[{\"name\":\"本地\",\"host\":\"localhost\",\"port\":3306,\"user\":\"root\",\"password\":\"root\"}]"
}

配置加载优先级

MYSQL_CONN_N_* 编号变量  >  MYSQL_CONNECTIONS JSON 变量  >  connections.json 文件

使用示例

配置完成后，直接在 AI 对话中说：

查看所有数据库连接
列出"本地开发"上的所有数据库
查看"测试服务器"中 mydb 的所有表
描述 mydb.users 表结构
在"本地开发"的 mydb 里搜索包含 order 的表
执行 SQL：SELECT * FROM mydb.orders WHERE status=1 LIMIT 20

安全说明

• run_query 拦截危险关键字：DROP、TRUNCATE、DELETE、ALTER、RENAME
• run_write 仅允许：INSERT、UPDATE、CREATE、ALTER
• connections.json 包含明文密码，请勿提交到 Git 仓库，建议加入 .gitignore

mcp-mysql-hub

中文 | English

A MySQL MCP Server supporting multiple database connections, designed for Cursor and Claude Code.
Switch freely between local, staging, and production MySQL environments in the same AI session.

Features

• 🔌 Multi-connection management — Manage multiple MySQL servers, switch by name
• 🗄️ Browse databases & tables — List databases, tables, and view table structure
• 🔍 Table search — Fuzzy search table names by keyword
• 📊 Data preview — Preview first N rows of any table
• 📝 SQL execution — Run SELECT queries and INSERT / UPDATE writes
• 🛡️ Safety guard — Blocks DROP / TRUNCATE / DELETE and other destructive operations

Available Tools

| Tool | Description | |------|-------------| | list_connections | List all configured database connections | | list_databases | List all databases on a connection | | list_tables | List all tables in a database | | describe_table | Show table structure (columns, types, indexes, CREATE statement) | | search_tables | Search tables by keyword | | table_data_preview | Preview first N rows of a table | | run_query | Execute read-only SQL (SELECT / SHOW / DESCRIBE) | | run_write | Execute write SQL (INSERT / UPDATE / CREATE) |

Requirements

• Node.js >= 18 (run node --version to confirm)

Installation · Cursor

Edit ~/.cursor/mcp.json:

• Windows: C:\Users\<username>\.cursor\mcp.json
• macOS / Linux: ~/.cursor/mcp.json

{
  "mcpServers": {
    "mysql-hub": {
      "command": "npx",
      "args": ["-y", "mcp-mysql-hub"],
      "env": {
        "MYSQL_CONN_1_NAME":     "local",
        "MYSQL_CONN_1_HOST":     "localhost",
        "MYSQL_CONN_1_PORT":     "3306",
        "MYSQL_CONN_1_USER":     "root",
        "MYSQL_CONN_1_PASSWORD": "root",

        "MYSQL_CONN_2_NAME":     "staging",
        "MYSQL_CONN_2_HOST":     "192.168.1.100",
        "MYSQL_CONN_2_PORT":     "3306",
        "MYSQL_CONN_2_USER":     "admin",
        "MYSQL_CONN_2_PASSWORD": "yourpassword"
      }
    }
  }
}

Restart Cursor after saving. The mysql-hub tools will appear in the MCP tool list.

Installation · Claude Code (Claude Desktop)

Edit the Claude Desktop config file:

• Windows: C:\Users\<username>\.claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mysql-hub": {
      "command": "npx",
      "args": ["-y", "mcp-mysql-hub"],
      "env": {
        "MYSQL_CONN_1_NAME":     "local",
        "MYSQL_CONN_1_HOST":     "localhost",
        "MYSQL_CONN_1_PORT":     "3306",
        "MYSQL_CONN_1_USER":     "root",
        "MYSQL_CONN_1_PASSWORD": "root",

        "MYSQL_CONN_2_NAME":     "staging",
        "MYSQL_CONN_2_HOST":     "192.168.1.100",
        "MYSQL_CONN_2_PORT":     "3306",
        "MYSQL_CONN_2_USER":     "admin",
        "MYSQL_CONN_2_PASSWORD": "yourpassword"
      }
    }
  }
}

Restart Claude Desktop after saving.

Connection Configuration

Option 1: Numbered Environment Variables (Recommended)

Each field of each connection is its own environment variable. No extra files needed.

Naming rule: MYSQL_CONN_{index}_{field}, index starts from 1 and must be consecutive.

| Field | Required | Default | Description | |-------|:--------:|---------|-------------| | NAME | ✅ | — | Connection name (used when calling tools) | | HOST | ✅ | — | Database host address | | PORT | ❌ | 3306 | Port number | | USER | ✅ | — | Database username | | PASSWORD | ✅ | — | Database password |

Option 2: connections.json File

Create a connections.json file and point to it via cwd:

{
  "local": {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "root"
  },
  "staging": {
    "host": "192.168.1.100",
    "port": 3306,
    "user": "admin",
    "password": "yourpassword"
  }
}

Add cwd to your config:

{
  "mysql-hub": {
    "command": "npx",
    "args": ["-y", "mcp-mysql-hub"],
    "cwd": "/path/to/folder/with/connections.json"
  }
}

Option 3: MYSQL_CONNECTIONS JSON String

"env": {
  "MYSQL_CONNECTIONS": "[{\"name\":\"local\",\"host\":\"localhost\",\"port\":3306,\"user\":\"root\",\"password\":\"root\"}]"
}

Configuration Priority

MYSQL_CONN_N_* variables  >  MYSQL_CONNECTIONS JSON  >  connections.json file

Usage Examples

After setup, just talk to the AI naturally:

List all database connections
Show all databases on "local"
Show all tables in mydb on "staging"
Describe the structure of mydb.users
Search for tables containing "order" in mydb on "local"
Run SQL: SELECT * FROM mydb.orders WHERE status = 1 LIMIT 20

Security

• run_query blocks statements starting with: DROP, TRUNCATE, DELETE, ALTER, RENAME
• run_write only allows: INSERT, UPDATE, CREATE, ALTER
• connections.json contains plaintext passwords — do not commit to Git, add it to .gitignore

License

MIT © wangwenshuai