MCP MariaDB Server

Gestiona y consulta bases de datos MariaDB usando el Model Context Protocol (MCP), con soporte para búsqueda SQL y vectorial.

GitHub

202

Prueba este MCPPatrocinado

Documentación

MCP MariaDB Server

El MCP MariaDB Server proporciona una interfaz de Model Context Protocol (MCP) para gestionar y consultar bases de datos MariaDB, soportando tanto operaciones SQL estándar como búsqueda avanzada basada en vectores/embeddings. Diseñado para su uso con asistentes de IA, permite la integración perfecta de flujos de trabajo de datos impulsados por IA con bases de datos relacionales y vectoriales.

Tabla de Contenidos

Descripción General
Componentes Principales
Herramientas Disponibles
Embeddings y Almacén Vectorial
Configuración y Variables de Entorno
Consideraciones de Seguridad
Instalación y Configuración
Ejemplos de Uso
Integración - Claude desktop/Cursor/Windsurf
Registro (Logging)
Pruebas

Descripción General

El MCP MariaDB Server expone un conjunto de herramientas para interactuar con bases de datos MariaDB y almacenes vectoriales mediante un protocolo estandarizado. Soporta:

Listar bases de datos y tablas
Obtener esquemas de tablas
Ejecutar consultas SQL seguras de solo lectura
Crear y gestionar almacenes vectoriales para búsqueda basada en embeddings
Integración con proveedores de embeddings (actualmente OpenAI, Gemini y HuggingFace) (opcional)

Componentes Principales

server.py: Lógica principal del servidor MCP y definiciones de herramientas.
config.py: Carga la configuración desde el entorno y archivos .env.
embeddings.py: Gestiona la integración del servicio de embeddings (OpenAI).
tests/: Documentación y scripts de pruebas manuales y automatizadas.

Herramientas Disponibles

Herramientas Estándar de Base de Datos

list_databases
- Lista todas las bases de datos accesibles.
- Parámetros: Ninguno
list_tables
- Lista todas las tablas en una base de datos especificada.
- Parámetros: database_name (cadena, obligatorio)
get_table_schema
- Obtiene el esquema de una tabla (columnas, tipos, claves, etc.).
- Parámetros: database_name (cadena, obligatorio), table_name (cadena, obligatorio)
get_table_schema_with_relations
- Obtiene el esquema con relaciones de claves foráneas de una tabla.
- Parámetros: database_name (cadena, obligatorio), table_name (cadena, obligatorio)
execute_sql
- Ejecuta una consulta SQL de solo lectura (SELECT, SHOW, DESCRIBE).
- Parámetros: sql_query (cadena, obligatorio), database_name (cadena, opcional), parameters (lista, opcional)
- Nota: Aplica el modo de solo lectura si MCP_READ_ONLY está habilitado.
create_database
- Crea una nueva base de datos si no existe.
- Parámetros: database_name (cadena, obligatorio)

Herramientas de Almacén Vectorial y Embeddings (opcional)

Nota: Estas herramientas solo están disponibles cuando EMBEDDING_PROVIDER está configurado. Si no se establece ningún proveedor de embeddings, estas herramientas estarán deshabilitadas.

create_vector_store
- Crea un nuevo almacén vectorial (tabla) para embeddings.
- Parámetros: database_name, vector_store_name, model_name (opcional), distance_function (opcional, predeterminado: cosine)
delete_vector_store
- Elimina un almacén vectorial (tabla).
- Parámetros: database_name, vector_store_name
list_vector_stores
- Lista todos los almacenes vectoriales en una base de datos.
- Parámetros: database_name
insert_docs_vector_store
- Inserta documentos por lotes (y metadatos opcionales) en un almacén vectorial.
- Parámetros: database_name, vector_store_name, documents (lista de cadenas), metadata (lista opcional de diccionarios)
search_vector_store
- Realiza búsqueda semántica de documentos similares utilizando embeddings.
- Parámetros: database_name, vector_store_name, user_query (cadena), k (opcional, predeterminado: 7)

Embeddings y Almacén Vectorial

Descripción General

El MCP MariaDB Server proporciona capacidades opcionales de embeddings y almacén vectorial. Estas funciones se pueden habilitar configurando un proveedor de embeddings, o deshabilitarse por completo si solo necesita operaciones estándar de base de datos.

Proveedores Soportados

OpenAI
Gemini
Modelos abiertos de Huggingface

Configuración

EMBEDDING_PROVIDER: Establezca a openai, gemini, huggingface, o déjelo sin configurar para deshabilitar
OPENAI_API_KEY: Requerido si se utilizan embeddings de OpenAI
GEMINI_API_KEY: Requerido si se utilizan embeddings de Gemini
HF_MODEL: Requerido si se utilizan embeddings de HuggingFace (p. ej., "intfloat/multilingual-e5-large-instruct" o "BAAI/bge-m3")

Selección de Modelo

Los modelos predeterminados y permitidos son configurables en el código (DEFAULT_OPENAI_MODEL, ALLOWED_OPENAI_MODELS)
El modelo se puede seleccionar por solicitud o se utiliza el modelo configurado por defecto

Esquema del Almacén Vectorial

Una tabla de almacén vectorial tiene las siguientes columnas:

id: Clave primaria de autoincremento
document: Texto del documento
embedding: Tipo VECTOR (indexado para búsqueda de similitud)
metadata: JSON (metadatos opcionales)

Configuración y Variables de Entorno

Toda la configuración se realiza mediante variables de entorno (normalmente establecidas en un archivo .env):

Variable	Descripción	Requerido	Predeterminado
`DB_HOST`	Dirección del host de MariaDB	Sí	`localhost`
`DB_PORT`	Puerto de MariaDB	No	`3306`
`DB_USER`	Nombre de usuario de MariaDB	Sí
`DB_PASSWORD`	Contraseña de MariaDB	Sí
`DB_NAME`	Base de datos predeterminada (opcional; se puede establecer por consulta)	No
`DB_CHARSET`	Conjunto de caracteres para la conexión a la base de datos (p. ej., `cp1251`)	No	Predeterminado de MariaDB
`DB_SSL`	Habilitar SSL/TLS para la conexión a la base de datos (`true`/`false`)	No	`false`
`DB_SSL_CA`	Ruta al archivo de certificado CA para verificación SSL	No
`DB_SSL_CERT`	Ruta al archivo de certificado de cliente para autenticación SSL	No
`DB_SSL_KEY`	Ruta al archivo de clave privada del cliente para autenticación SSL	No
`DB_SSL_VERIFY_CERT`	Verificar certificado del servidor (`true`/`false`)	No	`true`
`DB_SSL_VERIFY_IDENTITY`	Verificar identidad del nombre de host del servidor (`true`/`false`)	No	`false`
`MCP_READ_ONLY`	Aplicar modo SQL de solo lectura (`true`/`false`)	No	`true`
`MCP_BLOCK_SENSITIVE_SHOW`	Bloquear comandos `SHOW` sensibles (`PROCESSLIST`, `GRANTS`, `VARIABLES`, `MASTER`/`REPLICA STATUS`, `BINARY LOGS`, etc.) que pueden filtrar texto de consultas entre conexiones, credenciales/privilegios o topología de replicación. Establecer independientemente de `MCP_READ_ONLY` (`true`/`false`)	No	`true`
`MCP_MAX_POOL_SIZE`	Tamaño máximo del pool de conexiones de BD	No	`10`
`EMBEDDING_PROVIDER`	Proveedor de embeddings (`openai`/`gemini`/`huggingface`)	No	`None` (Deshabilitado)
`OPENAI_API_KEY`	Clave API para embeddings de OpenAI	Sí (si EMBEDDING_PROVIDER=openai)
`GEMINI_API_KEY`	Clave API para embeddings de Gemini	Sí (si EMBEDDING_PROVIDER=gemini)
`HF_MODEL`	Modelos abiertos de Huggingface	Sí (si EMBEDDING_PROVIDER=huggingface)
`ALLOWED_ORIGINS`	Lista separada por comas de orígenes permitidos	No	Lista larga de orígenes permitidos correspondientes al uso local del servidor
`ALLOWED_HOSTS`	Lista separada por comas de hosts permitidos	No	`localhost,127.0.0.1`

Tenga en cuenta que si se utiliza 'http' o 'sse' como transporte, configurar la autenticación es importante para la seguridad si permite conexiones fuera de localhost. Debido a que diferentes organizaciones utilizan diferentes métodos de autenticación, el servidor no proporciona un método de autenticación predeterminado. Deberá configurar su propio método de autenticación. Afortunadamente, FastMCP proporciona una forma sencilla de hacerlo a partir de la versión 2.12.1. Consulte la documentación de FastMCP para obtener más información. Hemos proporcionado una configuración de ejemplo a continuación.

Ejemplo de archivo `.env`

Con soporte de embeddings (OpenAI):

DB_HOST=localhost
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_PORT=3306
DB_NAME=your_default_database

MCP_READ_ONLY=true
MCP_MAX_POOL_SIZE=10

EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=AI...
HF_MODEL="BAAI/bge-m3"

Sin soporte de embeddings:

DB_HOST=localhost
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_PORT=3306
DB_NAME=your_default_database
MCP_READ_ONLY=true
MCP_MAX_POOL_SIZE=10

Con SSL/TLS habilitado:

DB_HOST=your-remote-host.com
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_PORT=3306
DB_NAME=your_default_database

# Enable SSL
DB_SSL=true
DB_SSL_CA=~/.mysql/ca-cert.pem
DB_SSL_CERT=~/.mysql/client-cert.pem
DB_SSL_KEY=~/.mysql/client-key.pem
DB_SSL_VERIFY_CERT=true
DB_SSL_VERIFY_IDENTITY=false

MCP_READ_ONLY=true
MCP_MAX_POOL_SIZE=10

Nota sobre la configuración SSL:

Todas las rutas de certificados SSL admiten ~ para la expansión del directorio de inicio
DB_SSL_CA se utiliza para verificar el certificado del servidor
DB_SSL_CERT y DB_SSL_KEY se utilizan para la autenticación de certificados de cliente (TLS mutuo)
Establezca DB_SSL_VERIFY_CERT=false solo para pruebas con certificados autofirmados
Establezca DB_SSL_VERIFY_IDENTITY=true para habilitar la verificación estricta del nombre de host

Ejemplo de configuración de autenticación: Esta configuración utiliza autenticación web externa mediante GitHub o Google. Si tiene autenticación JWT interna (deseable para organizaciones que gestionan sus propios servicios), puede utilizar el proveedor JWT en su lugar.

# GitHub OAuth
export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.github.GitHubProvider
export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID="Ov23li..."
export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET="github_pat_..."

# Google OAuth
export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.google.GoogleProvider
export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID="123456.apps.googleusercontent.com"
export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET="GOCSPX-..."

Privilegios de Usuario de Base de Datos - IMPORTANTE

⚠️ La única forma de garantizar un acceso 100% de solo lectura con total certeza es configurar el usuario de MariaDB con los privilegios adecuados. El indicador READ_ONLY es un intento de mejor esfuerzo para prevenir operaciones de escritura, pero se basa en una lista blanca de consultas permitidas y, frente a un usuario verdaderamente adversario, no sustituye a los privilegios adecuados del usuario de la base de datos.

Para uso en producción, debe crear un usuario de base de datos dedicado con privilegios mínimos. Esto también se recomienda para mostrar al LLM solo los datos que pueda necesitar para realizar su tarea, incluso fuera del modo de solo lectura.

Instalación y Configuración

Requisitos

Python 3.11 (consulte .python-version)
uv (gestor de dependencias; instrucciones de instalación)
Servidor MariaDB (local o remoto)

Pasos

Clonar el repositorio
Instalar uv (si aún no está instalado):
```
pip install uv
```
Instalar dependencias
```
uv lock
uv sync
```
Crear .env en la raíz del proyecto (consulte Configuración)

Ejecutar el servidor

Entrada/Salida estándar (predeterminado):

uv run server.py

Transporte SSE:

uv run server.py --transport sse --host 127.0.0.1 --port 9001

Transporte HTTP (HTTP en streaming):

uv run server.py --transport http --host 127.0.0.1 --port 9001 --path /mcp

Ejemplos de Uso

Consulta SQL Estándar

{
  "tool": "execute_sql",
  "parameters": {
    "database_name": "test_db",
    "sql_query": "SELECT * FROM users WHERE id = %s",
    "parameters": [123]
  }
}

Crear Almacén Vectorial

{
  "tool": "create_vector_store",
  "parameters": {
    "database_name": "test_db",
    "vector_store_name": "my_vectors",
    "model_name": "text-embedding-3-small",
    "distance_function": "cosine"
  }
}

Insertar Documentos en el Almacén Vectorial

{
  "tool": "insert_docs_vector_store",
  "parameters": {
    "database_name": "test_db",
    "vector_store_name": "my_vectors",
    "documents": ["Sample text 1", "Sample text 2"],
    "metadata": [{"source": "doc1"}, {"source": "doc2"}]
  }
}

Búsqueda Semántica

{
  "tool": "search_vector_store",
  "parameters": {
    "database_name": "test_db",
    "vector_store_name": "my_vectors",
    "user_query": "What is the capital of France?",
    "k": 5
  }
}

Integración - Claude desktop/Cursor/Windsurf/VSCode

Opción 1: Comando Directo (stdio)

{
  "mcpServers": {
    "MariaDB_Server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mariadb-mcp-server/",
        "run",
        "server.py"
        ],
        "envFile": "path/to/mcp-server-mariadb-vector/.env"      
    }
  }
}

Opción 2: Transporte SSE

{
  "servers": {
    "mariadb-mcp-server": {
      "url": "http://{host}:9001/sse",
      "type": "sse"
    }
  }
}

Opción 3: Transporte HTTP

{
  "servers": {
    "mariadb-mcp-server": {
      "url": "http://{host}:9001/mcp",
      "type": "streamable-http"
    }
  }
}

Opción 4: Contenedor Docker

{
  "servers": {
    "mariadb-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "9001:9001",
        "-e",
        "DB_HOST=",
        "-e",
        "DB_PORT=",
        "-e",
        "DB_USER=",
        "-e",
        "DB_PASSWORD=",
        "-e",
        "DB_NAME=",
        "mariadb-mcp-server",
        "python",
        "src/server.py",
        "--host",
        "0.0.0.0",
        "--transport",
        "stdio"
      ]
    }
  }
}

Registro (Logging)

Los registros se escriben en logs/mcp_server.log de forma predeterminada.
Los mensajes de registro incluyen llamadas a herramientas, problemas de configuración, errores de embeddings y solicitudes de clientes.
El nivel de registro y la salida se pueden ajustar en el código (consulte config.py y la configuración del logger).

Pruebas

Las pruebas se encuentran en el directorio src/tests/.
Consulte src/tests/README.md para obtener una descripción general.
Las pruebas cubren tanto operaciones SQL estándar como operaciones de herramientas vectoriales/embeddings.

MCP MariaDB Server

Documentación

MCP MariaDB Server

Tabla de Contenidos

Descripción General

Componentes Principales

Herramientas Disponibles

Herramientas Estándar de Base de Datos

Herramientas de Almacén Vectorial y Embeddings (opcional)

Embeddings y Almacén Vectorial

Descripción General

Proveedores Soportados

Configuración

Selección de Modelo

Esquema del Almacén Vectorial

Configuración y Variables de Entorno

Ejemplo de archivo .env

Privilegios de Usuario de Base de Datos - IMPORTANTE

Instalación y Configuración

Requisitos

Pasos

Ejemplos de Uso

Consulta SQL Estándar

Crear Almacén Vectorial

Insertar Documentos en el Almacén Vectorial

Búsqueda Semántica

Integración - Claude desktop/Cursor/Windsurf/VSCode

Opción 1: Comando Directo (stdio)

Opción 2: Transporte SSE

Opción 3: Transporte HTTP

Opción 4: Contenedor Docker

Registro (Logging)

Pruebas

Ejemplo de archivo `.env`