Servidor MCP Metabase | Awesome MCP Servers

metabase-server Servidor MCP

Um servidor Model Context Protocol para integração com Metabase.

Este é um servidor MCP baseado em TypeScript que implementa integração com a API do Metabase. Ele permite que assistentes de IA interajam com o Metabase, fornecendo acesso a:

Dashboards, perguntas/cartões e bancos de dados como recursos
Ferramentas para listar e executar consultas do Metabase
Capacidade de visualizar e interagir com dados do Metabase

Funcionalidades

Recursos

Listar e acessar recursos do Metabase via URIs metabase://
Acessar dashboards, cartões/perguntas e bancos de dados
Tipo de conteúdo JSON para acesso a dados estruturados

Ferramentas

list_dashboards - Listar todos os dashboards no Metabase
list_cards - Listar todas as perguntas/cartões no Metabase
list_databases - Listar todos os bancos de dados no Metabase
execute_card - Executar uma pergunta/cartão do Metabase e obter resultados
get_dashboard_cards - Obter todos os cartões em um dashboard
execute_query - Executar uma consulta SQL em um banco de dados do Metabase

Configuração

Antes de executar o servidor, você precisa definir variáveis de ambiente para autenticação. O servidor suporta dois métodos:

Chave de API (Preferida):
- METABASE_URL: A URL da sua instância do Metabase (por exemplo, https://your-metabase-instance.com).
- METABASE_API_KEY: Sua chave de API do Metabase.
Nome de usuário/Senha (Alternativa):
- METABASE_URL: A URL da sua instância do Metabase.
- METABASE_USERNAME: Seu nome de usuário do Metabase.
- METABASE_PASSWORD: Sua senha do Metabase.

O servidor verificará primeiro METABASE_API_KEY. Se estiver definido, a autenticação por chave de API será usada. Se METABASE_API_KEY não estiver definido, o servidor usará como alternativa METABASE_USERNAME e METABASE_PASSWORD. Você deve fornecer credenciais para pelo menos um desses métodos.

Exemplo de configuração:

Usando chave de API:

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

Ou, usando nome de usuário/senha:

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

Você pode definir essas variáveis de ambiente no seu perfil de shell ou usar um arquivo .env com um pacote como dotenv.

Desenvolvimento

Instalar dependências:

npm install

Compilar o servidor:

npm run build

Para desenvolvimento com recompilação automática:

npm run watch

Instalação

# 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 com o Claude Desktop, adicione a configuração do servidor:

No MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json No 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: Você também pode definir essas variáveis de ambiente no seu sistema em vez de no arquivo de configuração, se preferir.

Instalando via Smithery

Para instalar o metabase-server para Claude Desktop automaticamente via Smithery:

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

Instalando via Claude Code CLI

Para instalar o 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

Ou usando chave 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

A configuração será gravada em ~/.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"
      }
    }
  }
}

Solução de problemas

Se o servidor MCP falhar ao conectar, verifique os logs:

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

Problemas comuns:

Variáveis de ambiente não configuradas ("env": {} está vazio)
Formato de URL inválido (deve incluir https://)
Credenciais incorretas

Depuração

Como os servidores MCP se comunicam via stdio, a depuração pode ser desafiadora. Recomendamos usar o MCP Inspector, que está disponível como um script de pacote:

npm run inspector

O Inspector fornecerá uma URL para acessar ferramentas de depuração no seu navegador.

Testes

Após configurar as variáveis de ambiente conforme descrito na seção "Configuração", você pode testar manualmente a autenticação do servidor. O MCP Inspector (npm run inspector) é uma ferramenta útil para enviar solicitações ao servidor.

1. Testando com autenticação por chave de API

Defina as variáveis de ambiente METABASE_URL e METABASE_API_KEY com a URL da sua instância do Metabase e uma chave de API válida.
Certifique-se de que METABASE_USERNAME e METABASE_PASSWORD não estejam definidas ou deixe-as, pois a chave de API deve ter precedência.
Inicie o servidor: npm run build && node build/index.js (ou use o método escolhido para executar o servidor, como via configuração do Claude Desktop).
Verifique os logs do servidor. Você deve ver uma mensagem indicando que está usando autenticação por chave de API (por exemplo, "Usando chave de API do Metabase para autenticação.").
Usando um cliente MCP ou o MCP Inspector, tente chamar uma ferramenta, por exemplo, tools/call com {"name": "list_dashboards"}.
Verifique se a chamada da ferramenta foi bem-sucedida e se você recebeu os dados esperados.

2. Testando com autenticação por nome de usuário/senha (Alternativa)

Certifique-se de que a variável de ambiente METABASE_API_KEY não esteja definida.
Defina METABASE_URL, METABASE_USERNAME e METABASE_PASSWORD com credenciais válidas para sua instância do Metabase.
Inicie o servidor.
Verifique os logs do servidor. Você deve ver uma mensagem indicando que está usando autenticação por nome de usuário/senha (por exemplo, "Usando nome de usuário/senha do Metabase para autenticação." seguido de "Autenticando com Metabase usando nome de usuário/senha...").
Usando um cliente MCP ou o MCP Inspector, tente chamar a ferramenta list_dashboards.
Verifique se a chamada da ferramenta foi bem-sucedida.

3. Testando falhas de autenticação

Chave de API inválida:
1. Defina METABASE_URL e uma METABASE_API_KEY inválida. Certifique-se de que as variáveis METABASE_USERNAME e METABASE_PASSWORD não estejam definidas.
2. Inicie o servidor.
3. Tente chamar uma ferramenta (por exemplo, list_dashboards). A chamada da ferramenta deve falhar, e os logs do servidor podem indicar um erro de autenticação do Metabase (por exemplo, "Erro da API do Metabase: X-API-Key inválida").
Nome de usuário/senha inválidos:
1. Certifique-se de que METABASE_API_KEY não esteja definida. Defina METABASE_URL e METABASE_USERNAME/METABASE_PASSWORD inválidos.
2. Inicie o servidor.
3. Tente chamar uma ferramenta. A chamada da ferramenta deve falhar devido à falha na autenticação da sessão. Os logs do servidor podem mostrar "Falha na autenticação" ou "Falha ao autenticar com o Metabase".
Credenciais ausentes:
1. Remova a definição de METABASE_API_KEY, METABASE_USERNAME e METABASE_PASSWORD. Defina apenas METABASE_URL.
2. Tente iniciar o servidor.
3. O servidor deve falhar ao iniciar e registrar uma mensagem de erro informando que as credenciais de autenticação (chave de API ou nome de usuário/senha) são necessárias (por exemplo, "As variáveis de ambiente (METABASE_URL e METABASE_API_KEY) ou (METABASE_URL, METABASE_USERNAME e METABASE_PASSWORD) são necessárias").

Metabase Server

Documentação