mcp-mysql-server 1.0.2

A Model Context Protocol (MCP) server for MySQL databases with multi-database support and read-only mode. Enables AI assistants to securely query multiple MySQL databases.

MCP MySQL Server

MySQL 数据库模型上下文协议 (MCP) 实现，支持与 MySQL 数据库的安全交互。该服务器组件促进 AI 应用程序（主机/客户端）与 MySQL 数据库之间的通信，使数据库探索和分析更加安全和结构化。

注意: MCP MySQL Server 不是设计为独立服务器，而是作为 AI 应用程序和 MySQL 数据库之间的通信协议实现。

功能特性

• 多数据库支持: 配置多个 MySQL 连接，每个连接作为独立的工具
• 只读模式: 将连接限制为仅执行 SELECT/SHOW/DESCRIBE 查询
• 列出可用的 MySQL 表作为资源（按连接分组）
• 读取表内容
• 执行 SQL 查询，具有适当的错误处理
• 通过环境变量或配置文件实现安全的数据库访问
• 全面的日志记录

安装

使用 uvx（推荐）

uvx mcp-mysql-server

使用 pip

pip install mcp-mysql-server

配置

多数据库配置（推荐）

您可以使用 JSON 配置文件或环境变量来配置多个 MySQL 连接。

选项 1：JSON 配置文件

创建 JSON 配置文件并设置 MYSQL_CONFIG_FILE 环境变量：

单数据库模式（每个连接一个默认数据库）：

{
  "connections": {
    "config_manage": {
      "host": "localhost",
      "port": 3306,
      "user": "your_username",
      "password": "your_password",
      "database": "mysql-config-manage"
    },
    "product_staging": {
      "host": "localhost",
      "port": 3306,
      "user": "your_username",
      "password": "your_password",
      "database": "mysql-product-sg-staging"
    }
  }
}

多数据库模式（一个连接可访问多个数据库，推荐用于大量数据库场景）：

当同一个 MySQL 服务器上有多个数据库需要访问时，使用 databases 数组指定允许访问的数据库列表。每个连接只生成一个工具，通过 database 参数指定要操作的数据库：

{
  "connections": {
    "local_server": {
      "host": "localhost",
      "port": 3306,
      "user": "your_username",
      "password": "your_password",
      "databases": ["config_manage", "product_staging", "user_center", "orders", "inventory"],
      "readonly": true
    },
    "production": {
      "host": "prod-db.example.com",
      "port": 3306,
      "user": "prod_user",
      "password": "prod_password",
      "databases": ["orders", "inventory", "analytics", "users", "logs"],
      "readonly": true
    }
  }
}

这将创建 2 个工具（而不是 10 个）：

• execute_sql_local_server - 可访问 5 个数据库
• execute_sql_production - 可访问 5 个数据库

调用时通过 database 参数指定目标数据库：

{
  "query": "SELECT * FROM users LIMIT 10",
  "database": "config_manage"
}

优势：当您有几十个数据库时，这种方式可以大大减少工具数量，避免工具列表过长。

选项 2：环境变量 JSON

设置 MYSQL_CONNECTIONS 环境变量为 JSON 字符串：

# 单数据库模式
MYSQL_CONNECTIONS='{"connections":{"config_manage":{"host":"localhost","port":3306,"user":"user","password":"pass","database":"db1"}}}'

# 多数据库模式（推荐）
MYSQL_CONNECTIONS='{"connections":{"server":{"host":"localhost","port":3306,"user":"user","password":"pass","databases":["db1","db2","db3","db4","db5"]}}}'

只读模式

您可以为任何连接启用只读模式，将其限制为仅执行 SELECT、SHOW、DESCRIBE 和 EXPLAIN 查询。当您希望防止意外的数据修改时，即使数据库用户具有写权限，这也很有用。

在 JSON 配置文件中

{
  "connections": {
    "production_readonly": {
      "host": "prod-db.example.com",
      "port": 3306,
      "user": "readonly_user",
      "password": "password",
      "database": "production",
      "readonly": true
    },
    "staging_full_access": {
      "host": "staging-db.example.com",
      "port": 3306,
      "user": "admin_user",
      "password": "password",
      "database": "staging",
      "readonly": false
    }
  }
}

使用传统环境变量

MYSQL_HOST=localhost
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database
MYSQL_READONLY=true  # 启用只读模式（接受: true, 1, yes）

只读模式下允许的查询

• SELECT - 读取数据
• SHOW - 显示表、数据库等
• DESCRIBE / DESC - 描述表结构
• EXPLAIN - 解释查询执行计划
• USE - 切换数据库

只读模式下被阻止的查询

• INSERT, UPDATE, DELETE - 数据修改
• CREATE, ALTER, DROP, TRUNCATE - 结构变更
• GRANT, REVOKE - 权限变更
• CALL - 存储过程（可能修改数据）
• 事务语句 (BEGIN, COMMIT, ROLLBACK)

单数据库配置（传统）

为了向后兼容，您仍然可以使用单数据库环境变量：

MYSQL_HOST=localhost     # 数据库主机
MYSQL_PORT=3306         # 可选：数据库端口（未指定时默认为 3306）
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database

使用方法

与 Claude Desktop 一起使用

多数据库配置

将以下内容添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "mysql": {
      "command": "uvx",
      "args": ["mcp-mysql-server"],
      "env": {
        "MYSQL_CONFIG_FILE": "/path/to/mysql_config.json"
      }
    }
  }
}

或者使用内联 JSON 配置：

{
  "mcpServers": {
    "mysql": {
      "command": "uvx",
      "args": ["mcp-mysql-server"],
      "env": {
        "MYSQL_CONNECTIONS": "{\"connections\":{\"config_manage\":{\"host\":\"localhost\",\"port\":3306,\"user\":\"user\",\"password\":\"pass\",\"database\":\"config_db\"},\"product_staging\":{\"host\":\"localhost\",\"port\":3306,\"user\":\"user\",\"password\":\"pass\",\"database\":\"product_db\"}}}"
      }
    }
  }
}

这将创建：

• 工具: execute_sql_config_manage, execute_sql_product_staging
• 资源: [config_manage] table_name, [product_staging] table_name

单数据库配置（传统）

{
  "mcpServers": {
    "mysql": {
      "command": "uvx",
      "args": ["mcp-mysql-server"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

与 Visual Studio Code / Cursor 一起使用

多数据库配置

将以下内容添加到您的 mcp.json：

{
  "servers": {
    "mysql": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-mysql-server"],
      "env": {
        "MYSQL_CONFIG_FILE": "/path/to/mysql_config.json"
      }
    }
  }
}

使用本地开发版本

要使用本地开发版本而不是发布的包：

{
  "servers": {
    "mysql": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-mysql-server",
        "run",
        "mcp-mysql-server"
      ],
      "env": {
        "MYSQL_CONFIG_FILE": "/path/to/mysql_config.json"
      }
    }
  }
}

单数据库配置（传统）

{
  "servers": {
    "mysql": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-mysql-server"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

开发

# 克隆仓库
git clone https://github.com/aahowe/mcp-mysql-server.git
cd mcp-mysql-server

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # 或在 Windows 上使用 `venv\Scripts\activate`

# 安装开发依赖
pip install -r requirements-dev.txt

# 运行测试
pytest

安全考虑

• 永远不要提交环境变量或凭据
• 使用具有最小所需权限的数据库用户
• 考虑在生产环境中实施查询白名单
• 监控和记录所有数据库操作

安全最佳实践

此 MCP 实现需要数据库访问才能运行。为了安全：

1. 创建专用 MySQL 用户，具有最小权限
2. 永远不要使用 root 凭据 或管理账户
3. 限制数据库访问 仅为必要的操作
4. 启用日志记录 以进行审计
5. 定期安全审查 数据库访问

⚠️ 重要：配置数据库访问时始终遵循最小权限原则。

许可证

MIT 许可证 - 请参阅 LICENSE 文件以获取详细信息。

贡献

1. Fork 此仓库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 开启 Pull Request