MCP Alchemy

Explora, consulta y analiza bases de datos compatibles con SQLAlchemy directamente desde tu escritorio.

GitHub
419
Prueba este MCPPatrocinado

Documentación

MCP Alchemy

PulseMCP Badge

Estado: Mantenido activamente y en uso diario. Las versiones probadas se publican en PyPI con etiquetas git, y los problemas y solicitudes de extracción se clasifican regularmente.

¡Deja que Claude sea tu experto en bases de datos! MCP Alchemy conecta Claude Desktop directamente a tus bases de datos, permitiéndole:

  • Ayudarte a explorar y comprender la estructura de tu base de datos
  • Asistir en la escritura y validación de consultas SQL
  • Mostrar relaciones entre tablas
  • Analizar grandes conjuntos de datos y crear informes
  • Claude Desktop puede analizar y crear artefactos para conjuntos de datos muy grandes usando claude-local-files.

Funciona con PostgreSQL, MySQL, MariaDB, SQLite, Oracle, MS SQL Server, CrateDB, Vertica, y una gran variedad de otras bases de datos compatibles con SQLAlchemy.

MCP Alchemy in action

Instalación

Asegúrate de tener uv instalado:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

Uso con Claude Desktop

Agrega a tu claude_desktop_config.json. Debes agregar el controlador de base de datos apropiado en el parámetro --with.

Nota: Después del lanzamiento de una nueva versión, puede haber un período de hasta 600 segundos mientras se limpia la caché local, lo que puede causar que uv genere un error de versionado. Reiniciar el cliente MCP nuevamente resuelve el error.

SQLite (integrado en Python)

{
  "mcpServers": {
    "my_sqlite_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2026.9.5.185701",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "sqlite:////absolute/path/to/database.db"
      }
    }
  }
}

PostgreSQL

{
  "mcpServers": {
    "my_postgres_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2026.9.5.185701", "--with", "psycopg2-binary",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "postgresql://user:password@localhost/dbname"
      }
    }
  }
}

MySQL/MariaDB

{
  "mcpServers": {
    "my_mysql_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2026.9.5.185701", "--with", "pymysql",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "mysql+pymysql://user:password@localhost/dbname"
      }
    }
  }
}

Microsoft SQL Server

{
  "mcpServers": {
    "my_mssql_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2026.9.5.185701", "--with", "pymssql",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "mssql+pymssql://user:password@localhost/dbname"
      }
    }
  }
}

Oracle

{
  "mcpServers": {
    "my_oracle_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2026.9.5.185701", "--with", "oracledb",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "oracle+oracledb://user:password@localhost/dbname"
      }
    }
  }
}

CrateDB

{
  "mcpServers": {
    "my_cratedb": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2026.9.5.185701", "--with", "sqlalchemy-cratedb>=0.42.0.dev1",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "crate://user:password@localhost:4200/?schema=testdrive"
      }
    }
  }
}

Para conectarse a CrateDB Cloud, usa una URL como crate://user:password@example.aks1.westeurope.azure.cratedb.net:4200?ssl=true.

Vertica

{
  "mcpServers": {
    "my_vertica_db": {
      "command": "uvx",
      "args": ["--from", "mcp-alchemy==2026.9.5.185701", "--with", "vertica-python",
               "--refresh-package", "mcp-alchemy", "mcp-alchemy"],
      "env": {
        "DB_URL": "vertica+vertica_python://user:password@localhost:5433/dbname",
        "DB_ENGINE_OPTIONS": "{\"connect_args\": {\"ssl\": false}}"
      }
    }
  }
}

Docker

Se publica una imagen de contenedor en GitHub Container Registry con controladores de bases de datos comunes (PostgreSQL, MySQL/MariaDB, MS SQL Server, Oracle) preinstalados:

{
  "mcpServers": {
    "my_db": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "DB_URL",
               "ghcr.io/runekaagaard/mcp-alchemy:latest"],
      "env": {
        "DB_URL": "postgresql://user:password@host.docker.internal/dbname"
      }
    }
  }
}

O constrúyela tú mismo con docker build -t ghcr.io/runekaagaard/mcp-alchemy .

Transportes

Por defecto, el servidor usa stdio. También puede servir a través de HTTP para clientes que se conecten de esa manera:

# Recommended HTTP transport (serves on http://HOST:PORT/mcp)
mcp-alchemy --transport streamable-http --host 127.0.0.1 --port 7000

# Legacy SSE transport, for older clients (serves on http://HOST:PORT/sse)
mcp-alchemy --transport sse --host 127.0.0.1 --port 7000

Variables de Entorno

  • DB_URL: URL de base de datos de SQLAlchemy (requerido)
  • CLAUDE_LOCAL_FILES_PATH: Directorio para conjuntos de resultados completos (opcional)
  • EXECUTE_QUERY_MAX_CHARS: Longitud máxima de salida (opcional, predeterminado 4000)
  • DB_ENGINE_OPTIONS: Cadena JSON que contiene opciones adicionales del motor SQLAlchemy (opcional)

Agrupación de Conexiones

MCP Alchemy utiliza agrupación de conexiones optimizada para servidores MCP de larga duración. La configuración predeterminada es:

  • pool_pre_ping=True: Prueba las conexiones antes de usarlas para manejar tiempos de espera de la base de datos y problemas de red
  • pool_size=1: Mantiene 1 conexión persistente (los servidores MCP normalmente manejan una solicitud a la vez)
  • max_overflow=2: Permite hasta 2 conexiones adicionales para capacidad de ráfaga
  • pool_recycle=3600: Refresca conexiones mayores a 1 hora (previene problemas de tiempo de espera)
  • isolation_level='AUTOCOMMIT': Asegura que cada consulta se confirme automáticamente

Estos valores predeterminados funcionan bien para la mayoría de las bases de datos, pero puedes anularlos mediante DB_ENGINE_OPTIONS:

{
  "DB_ENGINE_OPTIONS": "{\"pool_size\": 5, \"max_overflow\": 10, \"pool_recycle\": 1800}"
}

Para bases de datos con configuraciones de tiempo de espera agresivas (como el predeterminado de 8 horas de MySQL), la combinación de pool_pre_ping y pool_recycle asegura conexiones confiables.

API

Herramientas

  • all_table_names

    • Devuelve todos los nombres de tablas en la base de datos
    • No requiere entrada
    • Devuelve una lista de tablas separada por comas
    users, orders, products, categories

  • filter_table_names

    • Encuentra tablas que coincidan con una subcadena
    • Entrada: q (cadena)
    • Devuelve nombres de tablas coincidentes
    Input: "user"
Returns: "users, user_roles, user_permissions"

  • schema_definitions

    • Obtén el esquema detallado de las tablas especificadas
    • Entrada: table_names (cadena[])
    • Devuelve definiciones de tablas que incluyen:
      • Nombres y tipos de columnas
      • Claves primarias
      • Relaciones de claves foráneas
      • Indicadores de nulabilidad
    users:
    id: INTEGER, primary key, autoincrement
    email: VARCHAR(255), nullable
    created_at: DATETIME
    
    Relationships:
      id -> orders.user_id

  • execute_query

    • Ejecuta una consulta SQL con formato de salida vertical
    • Entradas:
      • query (cadena): consulta SQL
      • params (objeto, opcional): parámetros de consulta
    • Devuelve resultados en formato vertical limpio:
    1. row
id: 123
name: John Doe
created_at: 2024-03-15T14:30:00
email: NULL

Result: 1 rows
    • Características:
      • Truncamiento inteligente de resultados grandes
      • Acceso al conjunto de resultados completo mediante la integración con claude-local-files
      • Visualización limpia de valores NULL
      • Fechas con formato ISO
      • Separación clara de filas

Claude Local Files

Cuando claude-local-files está configurado:

  • Accede a conjuntos de resultados completos más allá de la ventana de contexto de Claude
  • Genera informes detallados y visualizaciones
  • Realiza análisis profundos en grandes conjuntos de datos
  • Exporta resultados para procesamiento adicional

La integración se activa automáticamente cuando se establece CLAUDE_LOCAL_FILES_PATH.

Desarrollo

Primero clona el repositorio de GitHub, instala las dependencias y el/los controlador(es) de base de datos de tu elección:

git clone git@github.com:runekaagaard/mcp-alchemy.git
cd mcp-alchemy
uv sync
uv pip install psycopg2-binary

Luego establece esto en claude_desktop_config.json:

...
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-alchemy", "-m", "mcp_alchemy.server", "main"],
...

Mis Otros Proyectos LLM

  • MCP Redmine - Deja que Claude Desktop gestione tus proyectos y problemas de Redmine.
  • MCP Notmuch Sendmail - Asistente de correo electrónico para Claude Desktop usando notmuch.
  • Diffpilot - Visor de diferencias git de múltiples columnas con agrupación y etiquetado de archivos.
  • Claude Local Files - Accede a archivos locales en los artefactos de Claude Desktop.

Listados en Directorios MCP

MCP Alchemy está listado en los siguientes sitios y repositorios de directorios MCP:

Contribuciones

¡Las contribuciones son bienvenidas con entusiasmo! Ya sea informes de errores, solicitudes de funciones, mejoras de documentación o contribuciones de código, toda aportación es valiosa. Siéntete libre de:

  • Abrir un problema para reportar errores o sugerir funciones
  • Enviar solicitudes de extracción con mejoras
  • Mejorar la documentación o compartir tus ejemplos de uso
  • Hacer preguntas y compartir tus experiencias

El objetivo es hacer que la interacción con bases de datos mediante Claude sea aún mejor, y tus ideas y contribuciones ayudan a lograrlo.

Licencia

Licencia Pública de Mozilla Versión 2.0