Servidor MCP de Metabase - Conecta asistentes de IA a tus análisis de Metabase

Un servidor del Protocolo de Contexto de Modelo (MCP) de alto rendimiento para Metabase, que permite a asistentes de IA como Claude, Cursor y otros clientes MCP interactuar sin problemas con tu instancia de Metabase. Consulta bases de datos, ejecuta SQL, gestiona paneles y automatiza flujos de trabajo de análisis con lenguaje natural a través de operaciones de base de datos impulsadas por IA.

Ideal para: Analistas de datos, desarrolladores y equipos que buscan integrar asistentes de IA con su plataforma de inteligencia empresarial Metabase para consultas SQL automatizadas, gestión de paneles y exploración de datos.

Características principales

Operaciones de base de datos

• Listar bases de datos: Explora todas las bases de datos configuradas en Metabase

• Descubrimiento de tablas: Explora tablas con metadatos y descripciones

• Inspección de campos: Obtén información detallada de campos/columnas con paginación inteligente

Consultas y análisis

• Ejecución de SQL: Ejecuta consultas SQL nativas con soporte para parámetros y plantillas

• Soporte para MongoDB: Ejecuta consultas nativas de MongoDB con conversión automática a JSON para tuberías de agregación

• Gestión de tarjetas: Ejecuta, crea y gestiona preguntas/tarjetas de Metabase (SQL y MongoDB)

• Organización de colecciones: Crea y gestiona colecciones para una mejor organización

• Consultas en lenguaje natural: Permite que los asistentes de IA traduzcan preguntas a consultas SQL o MongoDB

Autenticación y seguridad

• Soporte para claves API: Autenticación segura mediante claves API de Metabase (recomendado)

• Autenticación basada en sesión: Autenticación alternativa mediante correo electrónico/contraseña

• Variables de entorno: Gestión segura de credenciales mediante archivos .env

Integración con asistentes de IA

• Claude Desktop: Integración nativa con la IA Claude de Anthropic

• Cursor IDE: Integración perfecta para el desarrollo asistido por IA

• Cualquier cliente MCP: Compatible con todos los clientes del Protocolo de Contexto de Modelo

Rendimiento y fiabilidad mejorados

• Registro consciente del contexto: Registro en tiempo real con niveles de depuración, información, advertencia y error visibles para los clientes de IA

• Gestión de errores adecuada: Excepciones ToolError de FastMCP para mejores mensajes de error y depuración

• Pila de middleware: Middleware integrado de gestión de errores y registro para la fiabilidad en producción

• Mejores prácticas: Sigue los últimos patrones de FastMCP con prevención de duplicados y configuración limpia

• Python moderno: Utiliza sugerencias de tipo de Python 3.12+ (sintaxis |) para una mayor seguridad de tipos

Inicio rápido

Requisitos previos

• Python 3.12+

• Instancia de Metabase con acceso a la API

• Gestor de paquetes uvx o uv

Instalación

Opción 1: Usando uvx (Más fácil - No requiere instalación)

# Run directly without installing (like npx for Python)
uvx metabase-mcp

# With environment variables
METABASE_URL=https://your-instance.com METABASE_API_KEY=your-key uvx metabase-mcp

Opción 2: Instalar desde PyPI

# Install globally
uv tool install metabase-mcp

# Or with pip
pip install metabase-mcp

# Then run
metabase-mcp

Opción 3: Configuración de desarrollo (Desde el código fuente)

# Clone the repository
git clone https://github.com/cheukyin175/metabase-mcp.git
cd metabase-mcp

# Install dependencies
uv sync

# Run the server
uv run python server.py

Configuración

Crea un archivo .env con tus credenciales de Metabase:

cp .env.example .env

Opciones de configuración

Opción 1: Autenticación con clave API (Recomendado)

METABASE_URL=https://your-metabase-instance.com
METABASE_API_KEY=your-api-key-here

Opción 2: Autenticación con correo electrónico/contraseña

METABASE_URL=https://your-metabase-instance.com
METABASE_USER_EMAIL=your-email@example.com
METABASE_PASSWORD=your-password

Opcional: Tiempo de espera HTTP de la API de Metabase

METABASE_HTTP_TIMEOUT=30.0  # Default: 30.0 seconds

Opcional: Host/puerto personalizado para SSE/HTTP

HOST=localhost  # Default: 0.0.0.0
PORT=9000      # Default: 8000

Uso

Ejecutar el servidor

Inicio rápido (No requiere configuración)

# Run directly with uvx
uvx metabase-mcp

# With custom Metabase instance
METABASE_URL=https://your-instance.com METABASE_API_KEY=your-key uvx metabase-mcp

Desde el código fuente (Desarrollo)

# STDIO transport (default)
uv run python server.py

# SSE transport (uses HOST=0.0.0.0, PORT=8000 by default)
uv run python server.py --sse

# HTTP transport (uses HOST=0.0.0.0, PORT=8000 by default)
uv run python server.py --http

# Custom host and port via environment variables
HOST=localhost PORT=9000 uv run python server.py --sse
HOST=192.168.1.100 PORT=8080 uv run python server.py --http

Integración con Cursor

Puedes configurar Cursor manualmente editando tus ajustes de Cursor.

Para transporte SSE: Debes iniciar el servidor antes de usar Cursor:

uv run python server.py --sse

Integración con Claude Desktop

Opción 1: Usando uvx (Recomendado)

Añade esto a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
    "mcpServers": {
        "metabase-mcp": {
            "command": "uvx",
            "args": ["metabase-mcp"],
            "env": {
                "METABASE_URL": "https://your-metabase-instance.com",
                "METABASE_API_KEY": "your-api-key-here"
            }
        }
    }
}

Opción 2: Usando instalación local

Si has clonado el repositorio:

{
    "mcpServers": {
        "metabase-mcp": {
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "/absolute/path/to/metabase-mcp",
                "python",
                "server.py"
            ],
            "env": {
                "METABASE_URL": "https://your-metabase-instance.com",
                "METABASE_API_KEY": "your-api-key-here"
            }
        }
    }
}

Opción 3: Usando la CLI de FastMCP

fastmcp install server.py -n "Metabase MCP"

Herramientas disponibles

Operaciones de base de datos

Operaciones de consulta

Gestión de tarjetas

Gestión de colecciones

Métodos de transporte

El servidor admite múltiples métodos de transporte:

• STDIO (predeterminado): Para integración con IDE (Cursor, Claude Desktop)

• SSE: Eventos enviados por el servidor para aplicaciones web

• HTTP: HTTP estándar para acceso a la API

uv run python server.py                        # STDIO (default)
uv run python server.py --sse                  # SSE (HOST=0.0.0.0, PORT=8000)
uv run python server.py --http                 # HTTP (HOST=0.0.0.0, PORT=8000)
HOST=localhost PORT=9000 uv run python server.py --sse   # Custom host/port

Desarrollo

Configurar el entorno de desarrollo

# Install with dev dependencies
uv sync --group dev

# Or with pip
pip install -r requirements-dev.txt

Calidad del código

# Run linting
uv run ruff check .

# Format code
uv run ruff format .

# Type checking
uv run mypy server.py

Ejemplos de uso

Ejemplos de consultas

# List all databases
databases = await list_databases()

# Execute a SQL query
result = await execute_query(
    database_id=1,
    query="SELECT * FROM users LIMIT 10"
)

# Create and run a card
card = await create_card(
    name="Active Users Report",
    database_id=1,
    query="SELECT COUNT(*) FROM users WHERE active = true",
    collection_id=2
)

Estructura del proyecto

metabase-mcp/
├── server.py                 # Main MCP server implementation
├── pyproject.toml           # Project configuration and dependencies
└── .env.example             # Environment variables template

Contribución

¡Las contribuciones son bienvenidas! Por favor, siéntete libre de enviar una solicitud de extracción (Pull Request).

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles

Recursos

• Documentación de FastMCP

• Protocolo de Contexto de Modelo

• Documentación de la API de Metabase

• Documentación de Claude Desktop

• Cursor IDE

Palabras clave y temas

metabase mcp model-context-protocol claude cursor ai-assistant fastmcp sql database analytics business-intelligence bi data-analysis anthropic llm python automation api data-science query-builder natural-language-sql

Historial de estrellas

Si encuentras útil este proyecto, ¡por favor considera darle una estrella! Ayuda a otros a descubrir esta herramienta.

Casos de uso

• Consultas de base de datos en lenguaje natural: Pide a Claude que consulte tus bases de datos de Metabase usando inglés sencillo

• Generación automatizada de informes: Usa IA para crear y gestionar tarjetas y colecciones de Metabase

• Exploración de datos: Deja que los asistentes de IA te ayuden a descubrir información a partir de tus datos

• Asistencia en consultas SQL: Obtén ayuda para escribir y optimizar consultas SQL a través de IA

• Gestión de paneles: Automatiza la creación y organización de paneles de Metabase

• Flujos de trabajo de análisis de datos: Integra análisis impulsados por IA en tu flujo de trabajo de desarrollo