nucleoDocs/mcp-metabase-server/README.md

MCP Metabase Server

Servidor MCP (Model Context Protocol) para interactuar con Metabase API.

Instalación Rápida

claude mcp add --transport http nucleodocs-metabase https://metabase.nucleoriofrio.com/mcp

Características

Proporciona herramientas MCP para:

• metabase_cards: Listar y buscar cards/questions con soporte para verbose y paginación
• metabase_card_info: Obtener detalles de una card específica
• metabase_execute_card: Ejecutar cards con parámetros dinámicos
• metabase_create_card: Crear nuevas cards/questions
• metabase_update_card: Actualizar nombre y descripción de cards
• metabase_collections: Listar colecciones con soporte para verbose
• metabase_databases: Listar bases de datos con soporte para verbose y metadata
• metabase_dashboards: Listar dashboards
• metabase_dashboard_info: Obtener detalles de un dashboard

Parámetro verbose

Por defecto, las herramientas devuelven respuestas ligeras optimizadas para listados (reducción de ~90-95% en tamaño). Usa verbose: true para obtener toda la información disponible.

Beneficios:

• ⚡ Respuestas 10-20x más rápidas por defecto
• 💾 Reducción de 90-95% en uso de tokens
• 🎯 Solo pides información detallada cuando la necesitas

Herramientas con soporte verbose:

• metabase_cards
• metabase_databases
• metabase_collections

Variables de Entorno

PORT=3000                                    # Puerto del servidor (default: 3000)
METABASE_URL=http://metabase:3000           # URL de Metabase
METABASE_API_KEY=mb_xxxxxxxxxxxxx           # API Key de Metabase (requerida)

Autenticación

Este servidor usa API Keys de Metabase para autenticación.

Crear una API Key en Metabase:

1. Ve a Settings → Admin → API Keys
2. Crea una nueva API Key
3. Copia la key y configúrala como METABASE_API_KEY

Desarrollo Local

# Instalar dependencias
npm install

# Desarrollo con hot reload
npm run dev

# Build
npm run build

# Producción
npm start

Docker

# Build
docker build -t mcp-metabase-server .

# Run
docker run -p 3000:3000 \
  -e METABASE_URL=http://metabase:3000 \
  -e METABASE_API_KEY=mb_xxxxx \
  mcp-metabase-server

Uso con Claude Code

claude mcp add --transport http nucleodocs-metabase https://metabase.tudominio.com/mcp

Ejemplos de Uso

Listar cards (modo ligero - default)

{
  "action": "list",
  "pageSize": 20  // Máximo 100
}
// Respuesta: ~600 bytes por 20 cards (solo campos esenciales)

Listar cards (modo verbose - completo)

{
  "action": "list",
  "pageSize": 20,
  "verbose": true  // Incluye creator, dataset_query, parameters, etc.
}
// Respuesta: ~240 KB por 20 cards (todos los campos)

Buscar cards por nombre

{
  "action": "search",
  "query": "ventas"
}

Paginación

{
  "action": "list",
  "page": 2,
  "pageSize": 50
}
// Devuelve página 2 con 50 cards

Ejecutar card con parámetros

{
  "card_id": 123,
  "parameters": [
    {
      "type": "date/single",
      "target": ["variable", ["template-tag", "fecha_desde"]],
      "value": "2025-01-01"
    }
  ]
}

Crear nueva card con SQL nativa

{
  "name": "Reporte de Ventas",
  "description": "Ventas del último mes",
  "dataset_query": {
    "type": "native",
    "database": 2,
    "native": {
      "query": "SELECT * FROM ventas WHERE fecha >= {{fecha_desde}}",
      "template_tags": {
        "fecha_desde": {
          "type": "date",
          "name": "fecha_desde",
          "display_name": "Fecha Desde"
        }
      }
    }
  },
  "display": "table",
  "collection_id": 5
}

API Metabase

Documentación: https://www.metabase.com/docs/latest/api

Endpoints implementados:

• GET /api/card - Listar cards
• GET /api/card/:id - Obtener card
• POST /api/card/:id/query - Ejecutar card
• POST /api/card - Crear card
• PUT /api/card/:id - Actualizar card
• GET /api/collection - Listar colecciones
• GET /api/database - Listar bases de datos
• GET /api/database/:id/metadata - Metadata de BD
• GET /api/dashboard - Listar dashboards
• GET /api/dashboard/:id - Obtener dashboard

Licencia

MIT