Readme: Metabase MCP Server

Un servidor integral del Model Context Protocol (MCP) para la integración con Metabase, que proporciona a los asistentes de IA acceso completo a la plataforma de analítica de Metabase.

🚀 Inicio rápido

# Install and run with npx
export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key
npx @cognitionai/metabase-mcp-server

Related MCP server: Metabase MCP Server

✨ Características

🎯 Más de 81 herramientas disponibles - Cobertura completa de la API de Metabase

• 📊 Gestión de paneles (23 herramientas) - operaciones CRUD completas, gestión de tarjetas, compartición pública e incrustación

• 📈 Gestión de tarjetas/preguntas (21 herramientas) - ejecución de consultas, gestión de parámetros, consultas pivot y enlaces públicos

• 🗄️ Gestión de bases de datos (13 herramientas) - gestión de conexiones, sincronización de esquemas y ejecución de consultas

• 📋 Gestión de tablas (16 herramientas) - operaciones de metadatos, gestión de campos y operaciones de datos

• 🔍 Herramientas adicionales (9 herramientas) - colecciones, búsqueda, usuarios, seguimiento de actividad y enlaces de playground

📦 Instalación

💡 Recomendado: Node.js 20.19.0+ y npm 8.0.0+ para una compatibilidad óptima

Método 1: NPX (recomendado)

npx @cognitionai/metabase-mcp-server

Método 2: Instalación global

npm install -g @cognitionai/metabase-mcp-server
metabase-mcp-server

Método 3: Docker

docker run -it --rm \
  -e METABASE_URL=https://your-metabase-instance.com \
  -e METABASE_API_KEY=your_metabase_api_key \
  ghcr.io/CognitionAI/metabase-mcp-server

⚙️ Configuración

Variables de entorno

Autenticación con clave de API (recomendada):

export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key

Autenticación con usuario/contraseña (alternativa):

export METABASE_URL=https://your-metabase-instance.com
export METABASE_USERNAME=your_username
export METABASE_PASSWORD=your_password

Argumentos opcionales

El servidor admite argumentos de línea de comandos para personalizar la carga de herramientas:

• --essential (predeterminado): carga solo las herramientas esenciales

• --all: carga las más de 80 herramientas disponibles

• --write: carga solo las herramientas de escritura/modificación

• --read: carga solo las herramientas de solo lectura

# Using published package (recommended)
# Default behavior (essential tools only)
npx @cognitionai/metabase-mcp-server

# Load all tools
npx @cognitionai/metabase-mcp-server --all

# Load only write tools
npx @cognitionai/metabase-mcp-server --write

# Load only read-only tools
npx @cognitionai/metabase-mcp-server --read

# Using local development build
npm run build
node dist/server.js                    # Default (essential tools)
node dist/server.js --all             # All tools
node dist/server.js --write           # Write tools only
node dist/server.js --read            # Read-only tools only

🔌 Ejemplos de integración

Claude Desktop

Añade lo siguiente a la configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

Con el paquete publicado:

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

Con una compilación de desarrollo local:

{
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/path/to/metabase-mcp-server/dist/server.js"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

Con indicadores personalizados:

{
  "mcpServers": {
    "metabase-all": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server", "--all"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

Windsurf IDE

Añade lo siguiente a la configuración de MCP de Windsurf (~/.windsurf/mcp_config.json):

Con el paquete publicado:

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

Con una compilación de desarrollo local:

{
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/path/to/metabase-mcp-server/dist/server.js"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

Con indicadores personalizados:

{
  "mcpServers": {
    "metabase-read": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server", "--read"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    },
    "metabase-write": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server", "--write"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

🛠️ Herramientas disponibles

Operaciones principales

• list_dashboards - Lista todos los paneles

• get_dashboard - Obtiene un panel por su ID

• create_dashboard - Crea un nuevo panel

• update_dashboard - Actualiza un panel existente

• delete_dashboard - Elimina un panel

• copy_dashboard - Copia un panel

Gestión de tarjetas

• get_dashboard_cards - Obtiene todas las tarjetas del panel

• add_card_to_dashboard - Añade una tarjeta al panel

• remove_card_from_dashboard - Elimina una tarjeta del panel

• update_dashboard_card - Actualiza la posición o la configuración de la tarjeta

• execute_dashboard_card - Ejecuta una tarjeta específica del panel

Compartición pública e incrustación

• create_public_link - Crea un enlace público del panel

• delete_public_link - Elimina el enlace público del panel

• list_public_dashboards - Lista los paneles públicos

• list_embeddable_dashboards - Lista los paneles incrustables

Parámetros y consultas

• get_dashboard_param_values - Obtiene los valores de los parámetros

• search_dashboard_param_values - Busca valores de parámetros

• get_dashboard_param_remapping - Obtiene la reasignación de parámetros

• execute_dashboard_query - Ejecuta consultas del panel

Funciones avanzadas

• get_dashboard_related - Obtiene el contenido relacionado

• get_dashboard_query_metadata - Obtiene los metadatos de la consulta

• update_dashboard_cards - Actualiza tarjetas de forma masiva

• save_dashboard - Guarda los cambios del panel

• get_dashboard_items - Obtiene los elementos del panel

Operaciones principales

• list_cards - Lista todas las tarjetas/preguntas

• get_card - Obtiene una tarjeta por su ID

• create_card - Crea una nueva tarjeta

• update_card - Actualiza una tarjeta existente

• delete_card - Elimina una tarjeta

• copy_card - Copia una tarjeta

Ejecución de consultas

• execute_card - Ejecuta la consulta de la tarjeta

• execute_card_query_with_format - Ejecuta con un formato específico

• execute_pivot_card_query - Ejecuta una consulta pivot

• get_card_query_metadata - Obtiene los metadatos de la consulta

Gestión de tarjetas

• move_cards - Mueve tarjetas entre colecciones

• move_cards_to_collection - Mueve de forma masiva a una colección

• get_card_dashboards - Obtiene los paneles que contienen la tarjeta

• get_card_series - Obtiene los datos de la serie de la tarjeta

Parámetros y valores

• get_card_param_values - Obtiene los valores de los parámetros

• search_card_param_values - Busca valores de parámetros

• get_card_param_remapping - Obtiene la reasignación de parámetros

Compartición pública

• create_card_public_link - Crea un enlace público de la tarjeta

• delete_card_public_link - Elimina el enlace público de la tarjeta

• get_public_cards - Lista las tarjetas públicas

• get_embeddable_cards - Lista las tarjetas incrustables

Operaciones principales

• list_databases - Lista todas las bases de datos

• get_database - Obtiene los detalles de la base de datos

• create_database - Crea una conexión de base de datos

• update_database - Actualiza la configuración de la base de datos

• delete_database - Elimina la conexión de base de datos

Esquema y metadatos

• get_database_schema_tables - Obtiene las tablas de la base de datos

• get_database_schemas - Obtiene los esquemas de la base de datos

• get_database_metadata - Obtiene los metadatos completos

• sync_database_schema - Sincroniza los metadatos del esquema

Operaciones de consulta

• execute_query - Ejecuta consultas SQL

• execute_query_export - Ejecuta y exporta los resultados

Mantenimiento

• get_database_usage_info - Obtiene estadísticas de uso

• rescan_database_field_values - Vuelve a escanear los valores de los campos

Operaciones principales

• list_tables - Lista las tablas con filtrado

• get_table - Obtiene los detalles de la tabla

• update_table - Actualiza la configuración de la tabla

• update_tables - Actualiza tablas de forma masiva

Operaciones de datos

• get_table_data - Recupera los datos de la tabla

• append_csv_to_table - Añade datos CSV

• replace_table_csv - Reemplaza con datos CSV

Esquema y relaciones

• get_table_query_metadata - Obtiene los metadatos de la consulta

• get_table_fks - Obtiene las relaciones de claves foráneas

• get_table_related - Obtiene las tablas relacionadas

• sync_table_schema - Sincroniza el esquema de la tabla

Gestión de campos

• reorder_table_fields - Reordena la visualización de los campos

• rescan_table_field_values - Vuelve a escanear los valores de los campos

• discard_table_field_values - Descarta los valores almacenados en caché

Integración de tarjetas

• get_card_table_fks - Obtiene las claves foráneas de la tabla de la tarjeta

• get_card_table_query_metadata - Obtiene los metadatos de la tabla de la tarjeta

Colecciones

• list_collections - Lista todas las colecciones

• create_collection - Crea una nueva colección

• update_collection - Actualiza la colección

• delete_collection - Elimina la colección

• get_collection_items - Obtiene los elementos de la colección

Búsqueda y descubrimiento

• search_content - Busca en todo el contenido

Actividad y analítica

• get_recent_views - Obtiene la actividad reciente

• get_popular_items - Obtiene el contenido popular

Enlaces de playground

• get_metabase_playground_link - Genera enlaces interactivos de playground

🧪 Desarrollo

Configuración inicial

git clone https://github.com/CognitionAI/metabase-mcp-server.git
cd metabase-mcp-server
npm install

Compilación

npm run build

Modo de desarrollo

npm run watch

Depuración

Usa MCP Inspector para la depuración:

npm run inspector

🔍 Probar la autenticación

Autenticación con clave de API

1. Configura METABASE_URL y METABASE_API_KEY

2. Inicia el servidor y verifica que aparece "Using Metabase API Key" en los registros

3. Prueba con la herramienta list_dashboards

Autenticación con usuario/contraseña

1. Elimina METABASE_API_KEY

2. Configura METABASE_URL, METABASE_USERNAME y METABASE_PASSWORD

3. Inicia el servidor y verifica que aparece "Using username/password" en los registros

4. Prueba con la herramienta list_dashboards

🐛 Solución de problemas

Problemas comunes

Errores de autenticación:

• Verifica que tu URL de Metabase sea accesible

• Comprueba la validez de la clave de API en la configuración de administración de Metabase

• Asegúrate de que las credenciales de usuario/contraseña sean correctas

Problemas de conexión:

• Confirma que la instancia de Metabase está en ejecución

• Comprueba la conectividad de red

• Verifica los certificados SSL si usas HTTPS

Errores de ejecución de herramientas:

• Comprueba los permisos de Metabase para tu usuario o clave de API

• Verifica que el recurso solicitado existe

• Revisa los registros del servidor para ver mensajes de error detallados

📄 Licencia

Este proyecto está licenciado bajo la licencia MIT. Consulta el archivo LICENSE para obtener más detalles.

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Visita nuestro repositorio de GitHub para:

• 🐛 Informar de errores

• 💡 Solicitar funcionalidades

• 🔧 Enviar pull requests

• 📖 Mejorar la documentación

Directrices de desarrollo

1. Haz un fork del repositorio

2. Crea una rama de funcionalidad

3. Realiza tus cambios con pruebas

4. Asegúrate de que todas las pruebas pasan

5. Envía un pull request

🆘 Soporte

• 📚 Documentación

• 🐛 Seguimiento de incidencias

Hecho con ❤️ para el mundo