nucleoDocs/mcp-metabase-server/README.md

# MCP Metabase Server

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

## Instalación Rápida

```bash
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

```bash
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

```bash
# Instalar dependencias
npm install

# Desarrollo con hot reload
npm run dev

# Build
npm run build

# Producción
npm start
```

## Docker

```bash
# 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

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

## Ejemplos de Uso

### Listar cards (modo ligero - default)

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

### Listar cards (modo verbose - completo)

```typescript
{
  "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

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

### Paginación

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

### Ejecutar card con parámetros

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

### Crear nueva card con SQL nativa

```typescript
{
  "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