mcp-mysql-server

mcp-mysql-server

一个基于 FastMCP、通过标准输入/输出（stdio）与本地 MySQL 数据库交互的简单 Python 脚本。

概述

mcp-mysql-server 提供命令行界面，用于查询本地 MySQL 数据库并检查其架构。它专为本地开发环境设计，适合偏好轻量级脚本交互的场景。该脚本使用标准输入和输出传递命令与结果，便于与其他命令行工具和工作流集成。

功能

• 执行查询： 执行 SQL SELECT 语句，并以简单易读的格式查看结果。
• 数据操作： 使用 write_table 工具向表中插入数据。
• 架构检查： 获取数据库架构信息，包括：
  • 使用 list_tables 工具列出所有表。
  • 使用 get_table_schema 获取指定表的列及其数据类型。
• 连接测试： 测试数据库连接并获取服务器信息。
• 可配置的访问控制： 通过配置定义连接参数（主机、用户、密码、数据库），以安全地访问数据库。
• stdio 接口： 使用标准输入向脚本传递命令，并通过标准输出接收结果，便于编写脚本和实现自动化。
• 专注本地部署： 针对本地开发环境中的使用进行了优化。

开始使用

先决条件

• 系统已安装 Python 3.x。
• 本地 MySQL 服务器实例正在运行。
• 所需的 Python 库（使用 requirements.txt 文件安装）：

  pip install -r requirements.txt
  

安装

1. 将仓库下载或克隆到本地计算机。

配置

1. 在脚本所在目录创建配置文件（例如 config.ini），或在运行脚本时指定文件路径。配置文件格式如下：

   [mysql]
   host = localhost
   port = 3306  # Optional, defaults to 3306
   user = your_mysql_user
   password = your_mysql_password
   database = your_database_name
   

   注意： 请确保指定的 MySQL 用户拥有执行所需操作的必要权限。

用法

运行以下命令，并指定配置文件的路径：

python mcp-mysql-server.py --config config.ini

该脚本提供以下工具，可用于与 MySQL 数据库交互：

• test_connection：测试数据库连接并返回服务器信息。
• list_tables：列出当前数据库中的所有表。
• read_table：读取并返回指定表中的所有数据。
• write_table：向指定表中插入一行新数据。
• get_table_schema：返回指定表的架构（列定义）。
• execute_sql：执行自定义 SQL 查询并返回结果。

项目结构

• mcp-mysql-server.py：包含 MySQL MCP 服务实现的主脚本
• config.ini：MySQL 连接参数配置文件
• requirements.txt：Python 依赖项列表
• changes.log：项目变更日志

Docker 支持

本项目可通过 Docker Compose 在 Docker 容器中运行。此配置包括：

1. 一个包含示例数据的 MySQL 容器
2. MCP MySQL 服务容器

使用 Docker 运行

1. 确保系统已安装 Docker 和 Docker Compose。
2. 克隆此仓库。
3. 在仓库根目录运行：

docker-compose up -d

此操作将：

• 启动一个包含示例数据（users 和 posts 表）的 MySQL 服务器
• 启动连接到 MySQL 数据库的 MCP MySQL 服务

Docker 配置

在 Docker 中运行时会使用专用配置文件（config.docker.ini），该文件指向 MySQL 容器。

测试

我们提供了单元测试，以确保功能正常运行。测试使用模拟，避免需要实际的数据库连接。

在本地运行测试

# Make a copy of the main script with underscore naming
cp mcp-mysql-server.py mcp_mysql_server.py

# Run the tests
python -m unittest tests.py

使用 Docker 运行测试

docker-compose -f docker-compose.test.yml up --build

这将构建测试容器，并在其中运行单元测试。

开发

如果开发者希望扩展此工具，可以通过创建其他 MCP 工具来添加新功能。每个工具都是一个使用 @mcp.tool() 装饰的 Python 函数，用于处理特定的数据库操作。

添加新工具的示例：

@mcp.tool()
def my_new_tool(param1: str, param2: int) -> dict:
    """
    Documentation for the new tool.
    """
    connection = create_mysql_connection()
    cursor = connection.cursor()
    try:
        # Your tool implementation here
        return {"result": "success"}
    finally:
        cursor.close()
        connection.close()