mysql-client-mcp-py 0.2.0

MCP Server for MySQL-protocol databases - schema discovery, SQL analysis, safe execution

MySQL Client MCP Server (mysql-client-mcp-py)

支持 MySQL 协议的 MCP Server：连接与元数据发现、SQL 分析、安全执行（单条，DDL 不执行，写操作需确认）。

环境变量

必填（单连接）

变量	说明
DB_HOST	主机
DB_USER	用户名
DB_PASSWORD	密码
DB_PORT	端口，默认 3306
DB_DATABASE	默认库，可选

多环境（仅方式二：TEST_DB_PROFILES / UAT_DB_PROFILES / PROD_DB_PROFILES）

• 多环境只配三个变量：TEST_DB_PROFILES、UAT_DB_PROFILES、PROD_DB_PROFILES，每个为 JSON 数组 [{},{}]，表示该环境下的一条或多条连接。不需再配 DB_HOST/DB_USER/DB_PASSWORD。
• 每个数组项需含 host、port、user、password；可选 database、description、databases、name（子名）。
• Profile 名：test_0、test_1、test_finance（若该项含 "name":"finance"）、uat_0、prod_0 等。默认连接取 prod 下第一个（如 prod_0）。
• 单环境：不设任一 *_DB_PROFILES 时，只配 DB_HOST、DB_USER、DB_PASSWORD（及可选 DB_PORT、DB_DATABASE）。

示例（test / uat / prod 三环境）：

TEST_DB_PROFILES='[{"host":"test-db.example.com","port":3306,"user":"t1","password":"xxx","database":"app_test","description":"测试环境","databases":["app_test"]}]'
UAT_DB_PROFILES='[{"host":"uat-db.example.com","port":3306,"user":"u1","password":"yyy","database":"app_uat","description":"UAT环境","databases":["app_uat"]}]'
PROD_DB_PROFILES='[{"host":"db.example.com","port":3306,"user":"ro","password":"zzz","database":"app","description":"生产环境","databases":["app","report"]}]'

测试环境多条连接时，数组里放多项即可，例如：

TEST_DB_PROFILES='[{"host":"t1","port":3306,"user":"u","password":"p","database":"app"},{"host":"t2","port":3306,"user":"u","password":"p","database":"order","name":"order"}]'
# → profile 为 test_0、test_order

调用时传 connection="test_0" 或 connection="prod_0" 等指定用哪条。

让智能体根据自然语言选连接：每项可配 description，list_connections / db://config 会展示，便于将用户说的「测试」「生产」映射到 profile 名。

每个连接聚焦若干数据库：每项可配 databases：不配置 → 默认所有库；空数组 [] → 不允许任何库；非空数组 → 仅允许这些库。

安全与行为

变量	默认	说明
DB_READ_ONLY	false	为 true 时仅允许 SELECT
DB_MAX_SELECT_ROWS	10000	SELECT 单次最大行数
DB_QUERY_TIMEOUT_SECONDS	30	执行超时(秒)
DB_SLOW_QUERY_SECONDS	10	超过此秒数提示慢查询

安装与运行

# 开发
cd mysql-client-mcp-py
uv sync
uv run python -m mysql_client_mcp

# 或安装后
pip install -e .
DB_HOST=localhost DB_USER=root DB_PASSWORD=xxx mysql-client-mcp-py

Cursor / Claude 配置示例

发布到 PyPI 后（用户已 pip install mysql-client-mcp-py 或使用 uvx）：

Cursor 编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "database": {
      "command": "uvx",
      "args": ["mysql-client-mcp-py"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "root",
        "DB_PASSWORD": "your-password",
        "DB_DATABASE": "your_db"
      }
    }
  }
}

多环境示例（只配 TEST_DB_PROFILES / UAT_DB_PROFILES / PROD_DB_PROFILES，每项需含 host、port、user、password）：

{
  "mcpServers": {
    "database": {
      "command": "uvx",
      "args": ["mysql-client-mcp-py"],
      "env": {
        "TEST_DB_PROFILES": "[{\"host\":\"test-db.example.com\",\"port\":3306,\"user\":\"u\",\"password\":\"p\",\"database\":\"app\"}]",
        "UAT_DB_PROFILES": "[{\"host\":\"uat-db.example.com\",\"port\":3306,\"user\":\"u\",\"password\":\"p\",\"database\":\"app\"}]",
        "PROD_DB_PROFILES": "[{\"host\":\"db.example.com\",\"port\":3306,\"user\":\"ro\",\"password\":\"xxx\",\"database\":\"app\"}]"
      }
    }
  }
}

Claude Desktop 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "database": {
      "command": "uvx",
      "args": ["mysql-client-mcp-py"],
      "env": {
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_PASSWORD": "your-password",
        "DB_DATABASE": "your_db"
      }
    }
  }
}

若已用 pip 安装到当前环境，也可直接指定命令（无需 uvx）：

{
  "mcpServers": {
    "database": {
      "command": "mysql-client-mcp-py",
      "args": [],
      "env": {
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_PASSWORD": "your-password"
      }
    }
  }
}

本地开发（未发布、从源码运行）：

{
  "mcpServers": {
    "database": {
      "command": "uv",
      "args": ["run", "python", "-m", "mysql_client_mcp"],
      "cwd": "/path/to/mysql-client-mcp-py",
      "env": {
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_PASSWORD": "your-password",
        "DB_DATABASE": "your_db"
      }
    }
  }
}

工具

工具	说明
list_connections	列出可用连接（profile + 可选说明），便于按用户自然语言选 connection
list_databases	列出数据库
list_tables	列出指定库的表
describe_table	表结构（列、行数、大小）
analyze_sql	分析 SQL（支持多条），不执行
execute_sql	执行单条 SQL（DDL 不执行，写操作需 confirm=true）

资源

• db://config - 配置与安全策略摘要
• db://databases - 数据库列表
• db://tables/{database} - 表列表
• db://table/{database}/{table} - 单表结构

提示词

• ask_user_which_connection_prompt - 连接选择规则：一开始无已选配置，必须先 list_connections 并让用户选择；用户选择后记住该 connection，后续默认使用且不再提示；仅当用户明确要切换环境时，再次列出并让用户选择
• query_safely_prompt - 安全查询习惯
• explore_schema_prompt - 先看 Schema 再写 SQL
• switch_connection_prompt - 切换环境时带 connection 参数
• use_connection_from_natural_language_prompt - 列出配置让用户选择，并根据用户说法映射到 connection

设计文档

参见项目内 docs/plans/2025-03-14-database-mcp-design.md。

License

MIT