Metabase MCP Server

Metabase MCP Server

Autor: Hyeongjun Yu (@hyeongjun-dev)

Un servidor de Model Context Protocol que integra asistentes de IA con la plataforma de analítica de Metabase.

Descripción General

Este servidor MCP basado en TypeScript proporciona una integración perfecta con la API de Metabase, permitiendo que los asistentes de IA interactúen directamente con tus datos de analítica. Diseñado para Claude y otros asistentes de IA compatibles con MCP, este servidor actúa como un puente entre tu plataforma de analítica y la IA conversacional.

Características Principales

• Acceso a Recursos: Navega por los recursos de Metabase mediante URIs intuitivos metabase://
• Dos Métodos de Autenticación: Soporte para autenticación basada en sesión y por clave de API
• Acceso Estructurado a Datos: Respuestas en formato JSON para un fácil consumo por parte de los asistentes de IA
• Registro Exhaustivo: Registro detallado para facilitar la depuración y el monitoreo
• Manejo de Errores: Manejo robusto de errores con mensajes de error claros

Herramientas Disponibles

El servidor expone las siguientes herramientas para los asistentes de IA:

• list_dashboards: Recupera todos los paneles disponibles en tu instancia de Metabase
• list_cards: Obtén todas las preguntas/tarjetas guardadas en Metabase
• list_databases: Consulta todas las fuentes de base de datos conectadas
• execute_card: Ejecuta preguntas guardadas y recupera resultados con parámetros opcionales
• get_dashboard_cards: Extrae todas las tarjetas de un panel específico
• execute_query: Ejecuta consultas SQL personalizadas contra cualquier base de datos conectada

Configuración

El servidor admite dos métodos de autenticación:

Opción 1: Autenticación por Usuario y Contraseña

# Required
METABASE_URL=https://your-metabase-instance.com
METABASE_USER_EMAIL=your_email@example.com
METABASE_PASSWORD=your_password

# Optional
LOG_LEVEL=info # Options: debug, info, warn, error, fatal

Opción 2: Autenticación por Clave de API (Recomendada para Producción)

# Required
METABASE_URL=https://your-metabase-instance.com
METABASE_API_KEY=your_api_key

# Optional
LOG_LEVEL=info # Options: debug, info, warn, error, fatal

Puedes configurar estas variables de entorno directamente o usar un archivo .env con dotenv.

Instalación

Requisitos Previos

• Node.js 18.0.0 o superior
• Una instancia de Metabase activa con las credenciales adecuadas

Configuración de Desarrollo

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

# For development with auto-rebuild
npm run watch

Integración con Claude Desktop

Para usar con Claude Desktop, añade esta configuración del servidor:

MacOS: Edita ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: Edita %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "metabase-mcp-server": {
      "command": "/absolute/path/to/metabase-mcp-server/build/index.js",
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_USER_EMAIL": "your_email@example.com",
        "METABASE_PASSWORD": "your_password"
        // Or alternatively, use API key authentication
        // "METABASE_API_KEY": "your_api_key"
      }
    }
  }
}

Alternativamente, puedes usar la versión alojada de Smithery mediante npx con configuración JSON:

Autenticación por Clave de API:

{
  "mcpServers": {
    "metabase-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli@latest",
        "run",
        "@hyeongjun-dev/metabase-mcp-server",
        "--config",
        "{\"metabaseUrl\":\"https://your-metabase-instance.com\",\"metabaseApiKey\":\"your_api_key\",\"metabasePassword\":\"\",\"metabaseUserEmail\":\"\"}"
      ]
    }
  }
}

Autenticación por Usuario y Contraseña:

{
  "mcpServers": {
    "metabase-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli@latest",
        "run",
        "@hyeongjun-dev/metabase-mcp-server",
        "--config",
        "{\"metabaseUrl\":\"https://your-metabase-instance.com\",\"metabaseApiKey\":\"\",\"metabasePassword\":\"your_password\",\"metabaseUserEmail\":\"your_email@example.com\"}"
      ]
    }
  }
}

Depuración

Dado que los servidores MCP se comunican a través de stdio, usa el MCP Inspector para depurar:

npm run inspector

El Inspector proporcionará una interfaz basada en navegador para monitorear solicitudes y respuestas.

Soporte para Docker

Hay una imagen de Docker disponible para el despliegue en contenedores:

# Build the Docker image
docker build -t metabase-mcp-server .

# Run the container with environment variables
docker run -e METABASE_URL=https://your-metabase.com \
           -e METABASE_API_KEY=your_api_key \
           metabase-mcp-server

Consideraciones de Seguridad

• Recomendamos usar autenticación por clave de API para entornos de producción
• Mantén tus claves de API y credenciales seguras
• Considera usar secretos de Docker o variables de entorno en lugar de codificar credenciales
• Aplica medidas de seguridad de red adecuadas para restringir el acceso a tu instancia de Metabase

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.