MySQL MCP Server

Un servidor MySQL que se conecta a una base de datos utilizando variables de entorno para la configuración.

Documentación

MySQL MCP Server

Este proyecto es un servidor que interactúa con la base de datos MySQL utilizando el Model Context Protocol (MCP) de Smithery.

Instalación

Instalación mediante Smithery

Para instalar MySQL Server para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @aqaranewbiz/mysql-aqaranewbiz --client claude

Instalación manual

npx @aqaranewbiz/mysql-aqaranewbiz

Configuración

El servidor requiere que se establezcan las siguientes variables de entorno en su archivo de configuración de ajustes de MCP:

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@aqaranewbiz/mysql-aqaranewbiz"],
      "env": {
        "MYSQL_HOST": "your_host",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Herramientas disponibles

1. connect_db

Establece una conexión a la base de datos MySQL utilizando las credenciales proporcionadas.

use_mcp_tool({
  server_name: "mysql",
  tool_name: "connect_db",
  arguments: {
    host: "localhost",
    user: "your_user",
    password: "your_password",
    database: "your_database"
  }
});

2. query

Ejecuta consultas SELECT con parámetros opcionales de declaraciones preparadas.

use_mcp_tool({
  server_name: "mysql",
  tool_name: "query",
  arguments: {
    sql: "SELECT * FROM users WHERE id = ?",
    params: [1]
  }
});

3. execute

Ejecuta consultas INSERT, UPDATE o DELETE con parámetros opcionales de declaraciones preparadas.

use_mcp_tool({
  server_name: "mysql",
  tool_name: "execute",
  arguments: {
    sql: "INSERT INTO users (name, email) VALUES (?, ?)",
    params: ["John Doe", "john@example.com"]
  }
});

4. list_tables

Lista todas las tablas en la base de datos conectada.

use_mcp_tool({
  server_name: "mysql",
  tool_name: "list_tables",
  arguments: {}
});

5. describe_table

Obtiene la estructura de una tabla específica.

use_mcp_tool({
  server_name: "mysql",
  tool_name: "describe_table",
  arguments: {
    table: "users"
  }
});

Características principales

Conexión a la base de datos MySQL y ejecución de consultas
Proporciona una API estandarizada a través del protocolo MCP
Endpoints de API RESTful basados en FastAPI
Gestión de configuración mediante variables de entorno

Comenzando

Requisitos previos

Python 3.11 o superior
Servidor MySQL
Docker (opcional)

Configuración del entorno

Crear el archivo .env:

MYSQL_HOST=your_mysql_host
MYSQL_USER=your_mysql_user
MYSQL_PASSWORD=your_mysql_password
MYSQL_DATABASE=your_database_name

Métodos de instalación

Instalación local (recomendada)

Crear y activar un entorno virtual de Python:

# Windows
python -m venv venv
venv\Scripts\activate

# macOS/Linux
python3 -m venv venv
source venv/bin/activate

Instalar dependencias:

pip install -r requirements.txt

Ejecutar el servidor:

python mcp_server.py

Instalación con Docker

Construir la imagen de Docker:

docker build -t mysql-mcp-server .

Ejecutar el contenedor:

docker run -e MYSQL_HOST=host -e MYSQL_USER=user -e MYSQL_PASSWORD=pass -e MYSQL_DATABASE=db mysql-mcp-server

Configuración de desarrollo local

Configurar el entorno de desarrollo:

# 개발용 의존성 설치
pip install -r requirements-dev.txt  # 필요한 경우 생성

# 코드 포맷팅 및 린팅 설정
pip install black flake8

Ejecutar el código:

# 개발 모드로 실행
python mcp_server.py --dev

Ejecutar las pruebas:

# 테스트 실행
python -m pytest tests/

Endpoints de API

Consulta de información del servidor

GET /status

Devuelve el estado del servidor y la lista de herramientas disponibles.

Ejecución de consultas

POST /execute

Ejecuta consultas MySQL y devuelve los resultados.

Guía de desarrollo

Estructura del proyecto

@MCP-Server-for-Smithery/
├── mcp_server.py      # 메인 서버 코드
├── requirements.txt   # Python 의존성
├── Dockerfile        # Docker 설정
├── .env              # 환경 변수 (템플릿)
└── tests/            # 테스트 코드

Añadir nuevas funciones

Añadir una nueva herramienta en mcp_server.py
Añadir las dependencias necesarias en requirements.txt
Escribir código de prueba
Reconstruir la imagen de Docker (si se usa Docker)

Solución de problemas

Problemas comunes

Errores de conexión:
- Verificar que el servidor MySQL esté en ejecución
- Verificar que las variables de entorno estén configuradas correctamente
- Verificar que la biblioteca del cliente MySQL esté instalada en la instalación local
Errores de ejecución de consultas:
- Revisar la sintaxis SQL
- Verificar los permisos de la base de datos
- Verificar la versión del conector MySQL en la instalación local

Registro (logging)

El servidor registra los logs en la salida estándar por defecto. Para ajustar el nivel de registro en la instalación local:

python mcp_server.py --log-level DEBUG

Si se usa Docker, para ver los logs:

docker logs [container-id]

Contribuir

Crear un issue
Crear una rama (git checkout -b feature/AmazingFeature)
Confirmar los cambios (git commit -m 'Add some AmazingFeature')
Empujar la rama (git push origin feature/AmazingFeature)
Crear un Pull Request

Licencia

Este proyecto se distribuye bajo la licencia MIT. Para más detalles, consulte el archivo LICENSE.

Contacto

Si tiene preguntas, por favor cree un issue.