Metabase Server

Integra con Metabase para consultar bases de datos y visualizar datos. Requiere la URL de Metabase y la clave de API para la autenticación.

GitHub

150

Documentación

Servidor MCP de metabase-server

Un servidor de Protocolo de Contexto de Modelo (MCP) para la integración con Metabase.

Este es un servidor MCP basado en TypeScript que implementa la integración con la API de Metabase. Permite que los asistentes de IA interactúen con Metabase, proporcionando acceso a:

Paneles, preguntas/tarjetas y bases de datos como recursos
Herramientas para listar y ejecutar consultas de Metabase
Capacidad de ver e interactuar con los datos de Metabase

Características

Recursos

Listar y acceder a recursos de Metabase mediante URIs metabase://
Acceder a paneles, tarjetas/preguntas y bases de datos
Tipo de contenido JSON para acceso estructurado a datos

Herramientas

list_dashboards - Listar todos los paneles en Metabase
list_cards - Listar todas las preguntas/tarjetas en Metabase
list_databases - Listar todas las bases de datos en Metabase
execute_card - Ejecutar una pregunta/tarjeta de Metabase y obtener resultados
get_dashboard_cards - Obtener todas las tarjetas en un panel
execute_query - Ejecutar una consulta SQL contra una base de datos de Metabase

Configuración

Antes de ejecutar el servidor, debe configurar variables de entorno para la autenticación. El servidor admite dos métodos:

Clave de API (Preferida):
- METABASE_URL: La URL de su instancia de Metabase (por ejemplo, https://your-metabase-instance.com).
- METABASE_API_KEY: Su clave de API de Metabase.
Nombre de usuario/Contraseña (Alternativa):
- METABASE_URL: La URL de su instancia de Metabase.
- METABASE_USERNAME: Su nombre de usuario de Metabase.
- METABASE_PASSWORD: Su contraseña de Metabase.

El servidor primero verificará METABASE_API_KEY. Si está configurado, se utilizará la autenticación con clave de API. Si METABASE_API_KEY no está configurado, el servidor recurrirá a usar METABASE_USERNAME y METABASE_PASSWORD. Debe proporcionar credenciales para al menos uno de estos métodos.

Ejemplo de configuración:

Usando clave de API:

# Required environment variables
export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key

O, usando nombre de usuario/contraseña:

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

Puede configurar estas variables de entorno en su perfil de shell o usar un archivo .env con un paquete como dotenv.

Desarrollo

Instalar dependencias:

npm install

Compilar el servidor:

npm run build

Para desarrollo con recompilación automática:

npm run watch

Instalación

# Oneliner, suitable for CI environment
git clone https://github.com/imlewc/metabase-server.git && cd metabase-server && npm i && npm run build && npm link

Para usar con Claude Desktop, agregue la configuración del servidor:

En MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json En Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "metabase-server": {
      "command": "metabase-server",
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        // Use API Key (preferred)
        "METABASE_API_KEY": "your_metabase_api_key"
        // Or Username/Password (if API Key is not set)
        // "METABASE_USERNAME": "your_username",
        // "METABASE_PASSWORD": "your_password"
      }
    }
  }
}

Nota: También puede configurar estas variables de entorno en su sistema en lugar de en el archivo de configuración si lo prefiere.

Instalación mediante Smithery

Para instalar metabase-server para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @imlewc/metabase-server --client claude

Instalación mediante Claude Code CLI

Para instalar metabase-server para Claude Code CLI:

claude mcp add metabase-server -s user \
  -e METABASE_URL="https://your-metabase-instance.com" \
  -e METABASE_USERNAME="your-email@example.com" \
  -e METABASE_PASSWORD="your-password" \
  -- npx -y @imlewc/metabase-server

O usando clave de API (preferida):

claude mcp add metabase-server -s user \
  -e METABASE_URL="https://your-metabase-instance.com" \
  -e METABASE_API_KEY="your-api-key" \
  -- npx -y @imlewc/metabase-server

La configuración se escribirá en ~/.claude.json:

{
  "mcpServers": {
    "metabase-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@imlewc/metabase-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_USERNAME": "your-email@example.com",
        "METABASE_PASSWORD": "your-password"
      }
    }
  }
}

Solución de problemas

Si el servidor MCP no puede conectarse, revise los registros:

cat ~/.claude/debug/latest | grep -i metabase

Problemas comunes:

Variables de entorno no configuradas ("env": {} está vacío)
Formato de URL no válido (debe incluir https://)
Credenciales incorrectas

Depuración

Dado que los servidores MCP se comunican a través de stdio, la depuración puede ser desafiante. Recomendamos usar el Inspector MCP, que está disponible como script de paquete:

npm run inspector

El Inspector proporcionará una URL para acceder a las herramientas de depuración en su navegador.

Pruebas

Después de configurar las variables de entorno como se describe en la sección "Configuración", puede probar manualmente la autenticación del servidor. El Inspector MCP (npm run inspector) es una herramienta útil para enviar solicitudes al servidor.

1. Pruebas con autenticación de clave de API

Configure las variables de entorno METABASE_URL y METABASE_API_KEY con la URL de su instancia de Metabase y una clave de API válida.
Asegúrese de que METABASE_USERNAME y METABASE_PASSWORD no estén configuradas o déjelas, ya que la clave de API debe tener prioridad.
Inicie el servidor: npm run build && node build/index.js (o use su método elegido para ejecutar el servidor, como mediante la configuración de Claude Desktop).
Revise los registros del servidor. Debería ver un mensaje que indique que está usando autenticación con clave de API (por ejemplo, "Usando clave de API de Metabase para autenticación.").
Usando un cliente MCP o el Inspector MCP, intente llamar a una herramienta, por ejemplo, tools/call con {"name": "list_dashboards"}.
Verifique que la llamada a la herramienta sea exitosa y reciba los datos esperados.

2. Pruebas con autenticación de nombre de usuario/contraseña (Alternativa)

Asegúrese de que la variable de entorno METABASE_API_KEY no esté configurada.
Configure METABASE_URL, METABASE_USERNAME y METABASE_PASSWORD con credenciales válidas para su instancia de Metabase.
Inicie el servidor.
Revise los registros del servidor. Debería ver un mensaje que indique que está usando autenticación de nombre de usuario/contraseña (por ejemplo, "Usando nombre de usuario/contraseña de Metabase para autenticación." seguido de "Autenticando con Metabase usando nombre de usuario/contraseña...").
Usando un cliente MCP o el Inspector MCP, intente llamar a la herramienta list_dashboards.
Verifique que la llamada a la herramienta sea exitosa.

3. Pruebas de fallos de autenticación

Clave de API no válida:
1. Configure METABASE_URL y una METABASE_API_KEY no válida. Asegúrese de que las variables METABASE_USERNAME y METABASE_PASSWORD no estén configuradas.
2. Inicie el servidor.
3. Intente llamar a una herramienta (por ejemplo, list_dashboards). La llamada a la herramienta debería fallar, y los registros del servidor podrían indicar un error de autenticación de Metabase (por ejemplo, "Error de API de Metabase: X-API-Key no válida").
Nombre de usuario/contraseña no válidos:
1. Asegúrese de que METABASE_API_KEY no esté configurada. Configure METABASE_URL y METABASE_USERNAME/METABASE_PASSWORD no válidos.
2. Inicie el servidor.
3. Intente llamar a una herramienta. La llamada a la herramienta debería fallar debido a un fallo de autenticación de sesión. Los registros del servidor podrían mostrar "Autenticación fallida" o "No se pudo autenticar con Metabase".
Credenciales faltantes:
1. Desconfigure METABASE_API_KEY, METABASE_USERNAME y METABASE_PASSWORD. Configure solo METABASE_URL.
2. Intente iniciar el servidor.
3. El servidor debería fallar al iniciar y registrar un mensaje de error indicando que se requieren credenciales de autenticación (ya sea clave de API o nombre de usuario/contraseña) (por ejemplo, "Se requieren variables de entorno (METABASE_URL y METABASE_API_KEY) o (METABASE_URL, METABASE_USERNAME y METABASE_PASSWORD)").