read-only-local-mysql-mcp-server

MySQL MCP 服务

一个 Model Context Protocol（MCP）服务，可让 Claude Desktop 通过自然语言查询与 MySQL 数据库交互。

功能

• 通过 Claude Desktop 执行只读 SQL 查询
• 动态连接配置 — 可在运行时通过连接字符串连接到任意 MySQL 数据库
• 内置查询验证安全机制（仅允许 SELECT、WITH、SHOW、DESCRIBE 和 EXPLAIN，只允许一条语句，不允许注释），并使用服务端只读事务
• 轻松集成 Claude Desktop
• 以 JSON 格式返回查询结果
• 基于环境变量配置数据库凭据

快速开始

Claude Code 用户（推荐 — 最简单的方法）

claude mcp add mysql -s user -- npx -y @hovecapital/read-only-mysql-mcp-server@latest

然后设置数据库环境变量：

export DB_HOST=localhost
export DB_PORT=3306
export DB_DATABASE=your_database_name
export DB_USERNAME=your_username
export DB_PASSWORD=your_password

完成！ 重启 Claude Code 并询问：“我的数据库中有哪些表？”

Claude Desktop 用户（手动配置）

1. 打开配置文件：

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json

2. 添加以下配置：

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@hovecapital/read-only-mysql-mcp-server@latest"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

3. 保存、重启 Claude Desktop 并测试！

前置条件

• Node.js（v16 或更高版本）- 如果使用 mise，请相应地更新命令路径
• MySQL 数据库服务
• Claude Desktop 应用

安装

选项 1：从 MCP Registry 安装（推荐）

此服务已作为 capital.hove/read-only-local-mysql-mcp-server 发布到 Model Context Protocol Registry。

方法 A：Claude Code CLI（最简单！）

claude mcp add mysql -s user -- npx -y @hovecapital/read-only-mysql-mcp-server@latest

然后使用环境变量配置数据库凭据。重启 Claude Code 即可完成！

优点：

• 一条命令即可安装
• 无需手动编辑 JSON
• 自动配置

方法 B：手动配置 JSON

Claude Desktop：

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@hovecapital/read-only-mysql-mcp-server@latest"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

Claude Code：

编辑 ~/.config/claude-code/settings.json（macOS/Linux）或 %APPDATA%\claude-code\settings.json（Windows）：

{
  "mcp": {
    "servers": {
      "mysql": {
        "command": "npx",
        "args": ["-y", "@hovecapital/read-only-mysql-mcp-server@latest"],
        "env": {
          "DB_HOST": "localhost",
          "DB_PORT": "3306",
          "DB_DATABASE": "your_database_name",
          "DB_USERNAME": "your_username",
          "DB_PASSWORD": "your_password"
        }
      }
    }
  }
}

选项 2：从 npm 安装

npm install -g @hovecapital/read-only-mysql-mcp-server

选项 3：通过 Claude Code 安装

如果你正在使用 Claude Code，可以轻松安装此 MCP 服务：

# Clone the repository
git clone https://github.com/hovecapital/read-only-local-mysql-mcp-server.git
cd read-only-local-mysql-mcp-server

# Install dependencies and build
npm install
npm run build

然后将其添加到 MCP 设置中来配置 Claude Code。

选项 4：手动安装

1. 克隆或下载

将仓库保存到系统中的某个目录：

mkdir ~/mcp-servers/mysql
cd ~/mcp-servers/mysql
git clone https://github.com/hovecapital/read-only-local-mysql-mcp-server.git .

2. 安装依赖项

npm install
npm run build

配置

注意： 如果你通过选项 1（使用 npx 从 MCP Registry 安装）进行安装，则所有内容都已配置完成！本节适用于选择选项 2、3 或 4（npm 或手动安装）的用户。

Claude Code 配置

如果你通过手动安装的方式使用 Claude Code，请将 MySQL 服务添加到 MCP 设置中：

1. 打开 Claude Code 设置（通常位于 macOS/Linux 的 ~/.config/claude-code/settings.json，或 Windows 的 %APPDATA%\claude-code\settings.json）

2. 添加 MySQL MCP 服务配置：

{
  "mcp": {
    "servers": {
      "mysql": {
        "command": "node",
        "args": ["/absolute/path/to/read-only-local-mysql-mcp-server/dist/index.js"],
        "env": {
          "DB_HOST": "localhost",
          "DB_PORT": "3306",
          "DB_DATABASE": "your_database_name",
          "DB_USERNAME": "your_username",
          "DB_PASSWORD": "your_password"
        }
      }
    }
  }
}

1. 重启 Claude Code，使更改生效。

Claude Desktop 配置

如果你通过手动安装的方式使用 Claude Desktop，请打开 Claude Desktop 配置文件：

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

Windows：

%APPDATA%\Claude\claude_desktop_config.json

添加 MySQL 服务配置：

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["/absolute/path/to/read-only-local-mysql-mcp-server/dist/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

使用 mise 管理 Node.js

如果你使用 mise 管理 Node.js 版本，请确保在配置中使用 Node.js 可执行文件的完整路径。

环境变量

变量	描述	默认值
DB_HOST	MySQL 服务器主机名	mysql
DB_PORT	MySQL 服务器端口	3306
DB_DATABASE	数据库名称	database
DB_USERNAME	MySQL 用户名	root
DB_PASSWORD	MySQL 密码	（空）
DB_ALLOWED_HOSTS	连接字符串可指向的额外主机，以逗号分隔。DB_HOST 和环回地址始终允许。	（空）

用法

1. 更新配置后重启 Claude Desktop
2. 开始与 Claude 聊天，询问有关数据库的问题

示例查询

"Show me all tables in my database"
"What's the structure of the users table?"
"Get the first 10 records from the products table"
"How many orders were placed last month?"
"Show me users with email addresses ending in @gmail.com"

Claude 会自动将你的自然语言请求转换为合适的 SQL 查询，并在数据库中执行。

工具

connect

使用连接字符串连接到 MySQL 数据库。连接会持续供后续查询使用，直到更改或断开连接。

参数：

参数	必填	描述
connectionString	是	MySQL 连接字符串（例如，mysql://user:password@host:port/database）

disconnect

断开与当前运行时数据库的连接，并恢复为默认的环境变量配置连接。无需参数。

query

对当前连接的数据库运行只读 SQL 查询。

参数：

参数	必填	描述
sql	是	要执行的 SQL 查询（只读）
connectionString	否	MySQL 连接字符串，仅用于覆盖本次查询的当前连接

动态连接

服务支持在运行时切换数据库，无需重启。连接优先级如下：

1. 单次查询的 connectionString — 仅对单次查询覆盖所有设置
2. 运行时连接（来自 connect 工具）— 持续生效，直到调用 disconnect
3. 环境变量 — 默认回退选项

连接字符串格式：

mysql://username:password@hostname:port/database_name

主机名必须是 DB_HOST、环回地址，或列在 DB_ALLOWED_HOSTS 中。任何其他主机都会在尝试连接前被拒绝，因此无法使用这些工具探测网络。连接失败时会返回通用消息，真实错误会写入 stderr。

示例工作流：

1. connect → mysql://analyst:pass@prod-db:3306/analytics
2. query   → SELECT COUNT(*) FROM events
3. query   → SELECT * FROM users LIMIT 5 (uses the same analytics connection)
4. query   → SELECT * FROM orders LIMIT 5, connectionString: mysql://analyst:pass@prod-db:3306/sales
              (one-off override — does not change the stored connection)
5. disconnect → reverts to env var defaults

安全功能

只读操作

查询会经过两层检查：

1. 查询验证 — 语句必须以 SELECT、WITH、SHOW、DESCRIBE 或 EXPLAIN 开头，只能包含一条语句，不得包含注释，也不得在任何位置包含会改变状态的关键字（例如 UPDATE、DELETE、INTO OUTFILE、INTO DUMPFILE、LOAD_FILE、FOR UPDATE、EXPLAIN ANALYZE）。此检查会忽略字符串字面量和反引号标识符。
2. 服务器端只读事务 — 每个查询都会在执行前运行 SET SESSION TRANSACTION READ ONLY，因此 MySQL 本身会拒绝写入操作，包括存储函数中的写入操作。

同时使用仅具有 SELECT 权限的 MySQL 用户（见下文）。验证机制会阻止已知的绕过方式，但数据库权限才是最终保障。

推荐的数据库设置

为增强安全性，请为 MCP 服务创建专用的只读用户：

-- Create a read-only user
CREATE USER 'claude_readonly'@'localhost' IDENTIFIED BY 'secure_password';

-- Grant only SELECT permissions on your specific database
GRANT SELECT ON your_database_name.* TO 'claude_readonly'@'localhost';

-- Apply the changes
FLUSH PRIVILEGES;

故障排除

连接问题

1. 确认 MySQL 正在运行：检查 MySQL 服务器是否处于活动状态
2. 检查凭据：确保用户名和密码正确
3. 网络连接：确认 Claude Desktop 可以访问 MySQL 服务器

配置问题

1. 需要重启：更改配置后务必重启 Claude Desktop
2. 路径准确性：确保 dist/index.js 的绝对路径正确
3. JSON 语法：验证 claude_desktop_config.json 格式

调试模式

若要查看服务日志，可以手动运行服务：

node dist/index.js

文件结构

~/mcp-servers/mysql/
├── src/
│   └── index.ts
├── dist/
│   ├── index.js
│   └── index.d.ts
├── package.json
├── tsconfig.json
└── node_modules/

依赖项

• @modelcontextprotocol/sdk：MCP 协议实现
• mysql2：支持 Promise 的现代 MySQL Node.js 客户端

贡献

欢迎提交问题和改进建议！

许可证

本项目为开源项目，采用 MIT 许可证。

支持

如果遇到问题：

1. 查看上面的故障排除部分
2. 单独验证 MySQL 连接
3. 确保 Claude Desktop 已更新至最新版本
4. 查阅 Claude Desktop MCP 文档

---

注意：此服务旨在用于开发和分析。若用于生产环境，请考虑采取额外的安全措施并进行监控。