Metabase MCP Server

Metabase MCP Server

Autor: Hyeongjun Yu (@hyeongjun-dev)

Um servidor Model Context Protocol que integra assistentes de IA com a plataforma de análise Metabase.

Visão Geral

Este servidor MCP baseado em TypeScript fornece integração perfeita com a API do Metabase, permitindo que assistentes de IA interajam diretamente com seus dados analíticos. Projetado para Claude e outros assistentes de IA compatíveis com MCP, este servidor atua como uma ponte entre sua plataforma de análise e a IA conversacional.

Principais Recursos

• Acesso a Recursos: Navegue pelos recursos do Metabase via URIs intuitivos metabase://
• Dois Métodos de Autenticação: Suporte para autenticação por sessão e por chave de API
• Acesso Estruturado a Dados: Respostas formatadas em JSON para fácil consumo por assistentes de IA
• Registro Abrangente: Logging detalhado para fácil depuração e monitoramento
• Tratamento de Erros: Tratamento robusto de erros com mensagens claras

Ferramentas Disponíveis

O servidor expõe as seguintes ferramentas para assistentes de IA:

• list_dashboards: Recupere todos os dashboards disponíveis na sua instância do Metabase
• list_cards: Obtenha todas as perguntas/cartões salvos no Metabase
• list_databases: Visualize todas as fontes de banco de dados conectadas
• execute_card: Execute perguntas salvas e recupere resultados com parâmetros opcionais
• get_dashboard_cards: Extraia todos os cartões de um dashboard específico
• execute_query: Execute consultas SQL personalizadas em qualquer banco de dados conectado

Configuração

O servidor suporta dois métodos de autenticação:

Opção 1: Autenticação por Nome de Usuário e Senha

# 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

Opção 2: Autenticação por Chave de API (Recomendado para Produção)

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

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

Você pode definir essas variáveis de ambiente diretamente ou usar um arquivo .env com dotenv.

Instalação

Pré-requisitos

• Node.js 18.0.0 ou superior
• Uma instância ativa do Metabase com credenciais apropriadas

Configuração de Desenvolvimento

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

# For development with auto-rebuild
npm run watch

Integração com Claude Desktop

Para usar com o Claude Desktop, adicione esta configuração de servidor:

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

Windows: Edite %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, você pode usar a versão hospedada do Smithery via npx com configuração JSON:

Autenticação por Chave 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\":\"\"}"
      ]
    }
  }
}

Autenticação por Nome de Usuário e Senha:

{
  "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\"}"
      ]
    }
  }
}

Depuração

Como os servidores MCP se comunicam via stdio, use o MCP Inspector para depuração:

npm run inspector

O Inspector fornecerá uma interface baseada em navegador para monitorar requisições e respostas.

Suporte a Docker

Uma imagem Docker está disponível para implantação em contêineres:

# 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

Considerações de Segurança

• Recomendamos usar autenticação por chave de API para ambientes de produção
• Mantenha suas chaves de API e credenciais seguras
• Considere usar segredos do Docker ou variáveis de ambiente em vez de codificar credenciais
• Aplique medidas de segurança de rede apropriadas para restringir o acesso à sua instância do Metabase

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.