AI导哈

MySQL数据库交互服务器

一个生产级的MySQL数据库交互服务器，通过MCP协议使AI助手能够安全高效地与MySQL数据库进行交互。

  • by hightower9
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 hightower9/mysql-mcp-server

使用说明

MySQL MCP 服务器

一个用于MySQL数据库交互的生产级模型上下文协议（MCP）服务器。该服务器使像Claude这样的AI助手能够通过MCP协议安全高效地与MySQL数据库进行交互。

特点/功能

✨ 准备就绪，可用于生产

  • 具有可配置设置的连接池
  • 全面的错误处理和日志记录
  • 防止SQL注入和查询验证
  • 可配置的安全控制（只读、写入、DDL）

🔒（锁形图标，通常表示安全、保密或锁定状态） 安全第一

  • 查询验证和清理
  • 参数化查询
  • 可配置的操作限制
  • 最大结果集限制
  • 查询超时强制执行

🛠️（扳手，常用于表示工具或修理） MCP（可能指某种特定系统、平台或协议，具体需根据上下文确定）功能/能力

  • 工具执行查询，列出表，描述模式，搜索表，数据库统计
  • 资源访问数据库模式、表结构和数据预览
  • 提示引导式表格分析、查询生成、优化及迁移规划

安装

先决条件

  • Python 3.10或更高版本
  • MySQL 5.7或更高版本（或MariaDB 10.2+）
  • pip 或 uv 包管理器

设置

  1. 克隆仓库：
git clone <repository-url>
cd mysql-mcp-server
  1. 创建并激活虚拟环境：
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. 安装依赖项：
pip install -e .
# Or for development:
pip install -e ".[dev]"
  1. 配置环境变量：
cp .env.example .env
# Edit .env with your MySQL credentials

配置

编辑 .env 保存您的设置文件：

# Required
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database

# Optional Security Settings
ENABLE_READ_ONLY=false
ENABLE_WRITE_OPERATIONS=true
ENABLE_DDL_OPERATIONS=false
MAX_QUERY_RESULTS=1000
QUERY_TIMEOUT=30

安全配置

  • ENABLE_READ_ONLY仅限制为SELECT查询
  • ENABLE_WRITE_OPERATIONS允许执行插入、更新、删除操作
  • ENABLE_DDL_OPERATIONS允许执行创建、修改、删除、清空表的操作
  • MAX_QUERY_RESULTS每查询返回的最大行数
  • QUERY_TIMEOUT最大查询执行时间（以秒为单位）

使用方法

启动服务器

# Using the installed command
mysql-mcp-server

# Or directly with uv
uv run python -m server.main

# Or directly with Python
python -m server.main

与Claude Desktop一起使用

在您的Claude桌面配置文件中添加：

MacOS（注：MacOS是苹果公司为其Mac电脑系列开发的操作系统，通常简称为“Mac”）： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": ["run", "python", "-m", "server.main"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

可用工具

1. 执行查询

在数据库上执行SQL查询：

# SELECT query
execute_query("SELECT * FROM users WHERE age > 25 LIMIT 10")

# INSERT query
execute_query("INSERT INTO users (name, email) VALUES ('John', 'john@example.com')")

# UPDATE query
execute_query("UPDATE users SET status = 'active' WHERE id = 1")

2. 列出表（list_tables）

获取数据库中的所有表：

list_tables()
# Returns: {"success": true, "tables": ["users", "orders", "products"], "count": 3}

3. 描述表

获取表的详细模式：

describe_table("users")
# Returns full schema including columns, types, constraints, indexes

4. 获取表信息

获取表的摘要信息：

get_table_info("products")
# Returns: row count, column count, column names, primary key info

5. 搜索表（search_tables）

按名称搜索表格：

search_tables("user")
# Returns tables containing "user" in the name

6. 获取数据库统计信息

获取数据库整体统计信息：

get_database_stats()
# Returns: table count, largest tables, configuration settings

可用资源

模式资源

mysql://schema

返回完整的数据库架构。

表模式资源

mysql://tables/{table_name}

返回特定表的架构。

表格预览资源

mysql://tables/{table_name}/preview

返回表的前10行。

可用提示

分析表

生成表结构和数据的分析。

生成查询（或生成查询语句）

根据自然语言描述创建SQL查询。

优化查询

获取SQL查询的优化建议。

数据库迁移

规划数据库模式迁移。

项目结构

mysql-mcp-server/
├── server/
│   ├── __init__.py           # Package initialization
│   ├── main.py               # FastAPI application entry point
│   ├── config/
│   │   ├── __init__.py       # Config package init
│   │   ├── settings.py       # Configuration management
│   │   └── database.py       # Database operations
│   ├── core/
│   │   ├── __init__.py       # Core package init
│   │   ├── prompts.py        # MCP prompt definitions
│   │   ├── resources.py      # MCP resource definitions
│   │   └── tools.py          # MCP tool definitions
│   └── utils/
│       ├── __init__.py       # Utils package init
│       └── security.py       # Security validation
├── .env.example              # Example environment variables
├── .gitignore                # Git ignore rules
├── pyproject.toml            # Project metadata and dependencies
└── README.md                 # Project README

安全最佳实践

  1. 永远不要承诺 .env 文件 - 包含敏感凭据
  2. 使用只读模式 用于分析任务
  3. 禁用DDL操作 除非明确需要
  4. 设置适当的查询超时时间 防止长时间运行的查询
  5. 限制最大结果数 以防止内存问题
  6. 定期进行安全审计 查询日志的

故障排除

连接问题

Error: Failed to connect to database
  • 验证MySQL是否正在运行
  • 检查 .env 文件中的主机、端口、用户名和密码
  • 确保数据库存在
  • 检查防火墙设置

权限错误

Error: Access denied for user
  • 授予适当的MySQL权限：
GRANT SELECT, INSERT, UPDATE, DELETE ON database_name.* TO 'username'@'host';
FLUSH PRIVILEGES;

查询验证错误

Error: Dangerous keyword detected
  • 安全验证器阻止了潜在有害的操作
  • 评论 security.py 对于允许的操作
  • 调整 ENABLE_DDL_OPERATIONS 如需

性能优化

  1. 连接池调整 POOL_SIZE 基于负载
  2. 查询限制设置 MAX_QUERY_RESULTS 适当地
  3. 索引确保在经常查询的列上建立适当的索引
  4. 泳池循环过滤调整 POOL_RECYCLE 对于长时间运行的服务器

许可证

麻省理工学院许可证

贡献；做出贡献

欢迎投稿！请：

  1. 克隆该仓库
  2. 创建一个特性分支
  3. 为新功能添加测试
  4. 确保所有测试通过
  5. 提交拉取请求

支持

对于问题和疑问：

  • 在GitHub上创建一个问题
  • 检查现有问题以寻找解决方案
  • 查看MCP（模型上下文协议）文档，请访问：https://modelcontextprotocol.io

更新日志

版本1.0.0

  • 初步生产发布
  • 完整的MCP实现
  • 安全验证
  • 连接池
  • 全面的文档记录

相关 MCP