servidor mysql-mcp

README.md de Corea del Sur

0. Ejecución

Ejecutando con Docker

Cambie la información de conexión de la base de datos según sea necesario.

docker run -d --name mcp-mysql \
  -e MYSQL_HOST=localhost \
  -e MYSQL_PORT=3306 \
  -e MYSQL_USER=root \
  -e MYSQL_PASSWORD=mcpTest1234!!! \
  -e MYSQL_DATABASE=mcp_test \
  -e MCP_PORT=8081 \
  -p 3306:3306 mineru/mcp-mysql:1.0.0

Ejecutar con Docker Compose

Esto procederá con una configuración preconfigurada.

docker-compose up -d

Ejecutando directamente con Python

pip install -r requirements.txt
python mysql_mcp_server/main.py run

Configuración del cursor

La funcionalidad MCP está disponible desde la versión 0.46 de Cursor y superiores.

Además, la función MCP solo está accesible para los usuarios de cuentas Cursor Pro.

Consejos para añadir herramientas

• Agregar una herramienta

  • Las funciones execute implementan la ejecución de la lógica real (capa de servicio).

  • El decorador @tool ayuda a registrar la herramienta con MCP (capa de controlador).

• Explicación

  • Cada archivo bajo mysql_mcp_server/executors representa una sola herramienta.

  • Si se agrega una nueva herramienta, debe importarse en mysql_mcp_server/executors/__init__.py e incluirse en la matriz __all__ .

  • Esto garantiza que el módulo se registre automáticamente en la variable TOOLS_DEFINITION .

flowchart LR;
    A[AI Model] -->|Request tool list| B[MCP Server]
    B -->|Return available tools| A

    A -->|Request specific tool execution| B
    B -->|Call the corresponding executor| C[Executors]
    
    subgraph Executors
        C1[execute_create_table] -->|Create table| D
        C2[execute_desc_table] -->|View table schema| D
        C3[execute_explain] -->|Query execution plan| D
        C4[execute_insert_query] -->|Execute INSERT query| D
        C5[execute_insight_starter] -->|Checking the schema for building reports| D
        C6[execute_invoke_viz_pro] -->|Visualization chart recommendations| D
        C7[execute_select_query] -->|Execute SELECT query| D
        C8[execute_show_tables] -->|Retrieve table list| D
    end

    D[DatabaseManager] -->|Connect to MySQL| E[MySQL 8.0]

    E -->|Return results| D
    D -->|Send results| C
    C -->|Return results| B
    B -->|Return execution results| A

Related MCP server: MCP MySQL Server

Hoja de ruta de desarrollo

• ⚙️ Opciones de parámetros

  • [ ] 🔧 Habilitar/Deshabilitar interruptor para cada herramienta: Proporciona una función para reducir los costos de contexto de entrada 💰

  • [ ] 🔒 Configuración del nivel de seguridad de la consulta: ofrece control opcional sobre funciones que podrían dañar el valor del activo, como ELIMINAR, ELIMINAR, ACTUALIZAR 🚫

• ✨ Características

  • [x] 📊 Generación de informes de análisis de datos: proporcione una función de generación de informes optimizada para el modelo para seleccionar adecuadamente varios gráficos en función de las solicitudes de los usuarios 📈

    • [x] 📝 Capacidades de generación de informes para formularios prescritos

    • [ ] 🖌️ Plantillas de informes de Diversify

  • [ ] 🗄️ Soporte extendido para Text2SQL

  • [ ] 🌐 Compatibilidad con conexión SSH: habilite el acceso remoto seguro a través de SSH para operaciones avanzadas 🔑

  • [ ] 📥 Función de extracción de archivos

    • [ ] 📄 CSV

    • [ ] 📑 JSON

    • [ ] 📉 Excel

1. Descripción general

MCP MySQL Server es una aplicación de servidor para operaciones de bases de datos MySQL basada en MCP (Protocolo de Contexto de Modelo). Este servidor proporciona herramientas que permiten a los modelos de IA interactuar con la base de datos MySQL.

2. Configuración del sistema

2.1 Componentes clave

• Servidor MCP : un servidor FastMCP que se comunica con modelos de IA

• Base de datos MySQL : administra y almacena datos

• Herramientas : Ejecutores que realizan operaciones de base de datos

2.2 Pila tecnológica

• Lenguaje : Python

• Base de datos : MySQL 8.0

• Bibliotecas clave :

  • mcp: Implementa el Protocolo de Contexto de Modelo para la comunicación de IA

  • PyMySQL: se conecta a MySQL y ejecuta consultas

  • pandas: procesa y analiza datos

  • python-dotenv: administra variables de entorno

  • fuego: Implementa interfaces de línea de comandos

2.3 Entorno de implementación

• Implementación en contenedores a través de Docker y Docker Compose

• Puertos: 8081 (Servidor MCP), 3306 (MySQL)

3. Estructura del directorio

MCPBoilerPlate/
├── mysql_mcp_server/           # Main application directory
│   ├── executors/              # Database operation executors
│   │   ├── create_table.py     # Tool for creating tables
│   │   ├── desc_table.py       # Tool for viewing table schema
│   │   ├── explain.py          # Tool for query execution plans
│   │   ├── insert_query.py     # Tool for INSERT query execution
│   │   ├── insight_starter.py  # Schema verification tools for write reports
│   │   ├── invoke_viz_pro.py   # Tool for Visualization chart recommendation
│   │   ├── select_query.py     # Tool for SELECT query execution
│   │   └── show_tables.py      # Tool for retrieving table lists
│   ├── helper/                 # Utility modules
│   │   ├── db_conn_helper.py   # Manages database connections
│   │   ├── logger_helper.py    # Logging utilities
│   │   └── tool_decorator.py   # Tool decorator
│   └── main.py                 # Application entry point
├── docker-compose.yml          # Docker Compose configuration
├── Dockerfile                  # Docker image build settings
├── requirements.txt            # Dependency package list
└── .env.example                # Example environment variables file

4. Diseño arquitectónico

4.1 Estructura en capas

1. Capa de interfaz : Servidor MCP (FastMCP)

2. Capa de lógica empresarial : controladores y ejecutores

3. Capa de acceso a datos : Conexión a la base de datos y ejecución de consultas

4.2 Clases y módulos clave

• MySQLMCPServer : clase de servidor principal que inicializa y ejecuta el servidor MCP

• DatabaseManager : administrador de conexiones de bases de datos basado en patrones Singleton

• Ejecutores : Colección de herramientas para operaciones de bases de datos

  • execute_create_table: Crea tablas

  • execute_desc_table: Comprueba el esquema de la tabla

  • execute_explain: Proporciona planes de ejecución de consultas

  • execute_insert_query: ejecuta consultas INSETR

  • execute_select_query: ejecuta consultas SELECT

  • execute_show_tables: recupera listas de tablas

4.3 Flujo de comunicación

1. El modelo de IA solicita una lista de herramientas disponibles del servidor MCP.

2. El servidor devuelve la lista de herramientas disponibles.

3. El modelo de IA solicita la ejecución de una herramienta específica.

4. El servidor llama al ejecutor correspondiente para realizar la operación de la base de datos.

5. Los resultados de la ejecución se devuelven al modelo de IA.

5. Escalabilidad y mantenimiento

• Agregar herramientas : implemente nuevas herramientas en el directorio executors y regístrelas en __init__.py .

• Configuración del entorno : administre las variables de entorno a través del archivo .env .

• Registro : asegúrese de que el registro sea consistente utilizando logger_helper .

6. Implementación y ejecución

6.1 Ejecución local

# Setup environment
cp .env.example .env
# Modify .env file as needed

# Install dependencies
pip install -r requirements.txt

# Run the server
python mysql_mcp_server/main.py run

6.2 Implementación de Docker

# Start database using Docker Compose
docker-compose up -d db
# Build and run mysql-mcp-server with Docker Compose (including rebuilds)
docker-compose up -d --build mysql-mcp-server

7. Consideraciones de seguridad

• Administrar las credenciales de la base de datos a través de variables de entorno.

• Utilice contraseñas seguras en entornos de producción.

• Considere implementar el cifrado SSL/TLS para las conexiones de bases de datos cuando sea necesario.