metabase-server MCP Server

A Model Context Protocol server for Metabase integration.

This is a TypeScript-based MCP server that implements integration with Metabase API. It allows AI assistants to interact with Metabase, providing access to:

• Dashboards, questions/cards, and databases as resources
• Tools for listing and executing Metabase queries
• Ability to view and interact with Metabase data

Features

Resources

• List and access Metabase resources via `metabase://` URIs
• Access dashboards, cards/questions, and databases
• JSON content type for structured data access

Tools

• `list_dashboards` - List all dashboards in Metabase
• `list_cards` - List all questions/cards in Metabase
• `list_databases` - List all databases in Metabase
• `execute_card` - Execute a Metabase question/card and get results
• `get_dashboard_cards` - Get all cards in a dashboard
• `execute_query` - Execute a SQL query against a Metabase database

Configuration

Before running the server, you need to set environment variables for authentication. The server supports two methods:

1. API Key (Preferred):

2. Username/Password (Fallback):

The server will first check for `METABASE_API_KEY`. If it's set, API key authentication will be used. If `METABASE_API_KEY` is not set, the server will fall back to using `METABASE_USERNAME` and `METABASE_PASSWORD`. You must provide credentials for at least one of these methods.

Example setup:

Using API Key:

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

Or, using Username/Password:

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

You can set these environment variables in your shell profile or use a `.env` file with a package like `dotenv`.

Development

Install dependencies:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

Installation

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

To use with Claude Desktop, add the server config:

On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

On 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"
      }
    }
  }
}

Note: You can also set these environment variables in your system instead of in the config file if you prefer.

Installing via Smithery

To install metabase-server for Claude Desktop automatically via Smithery:

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

Installing via Claude Code CLI

To install metabase-server for 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

Or using API Key (preferred):

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

Configuration will be written to `~/.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"
      }
    }
  }
}

Troubleshooting

If MCP server fails to connect, check the logs:

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

Common issues:

• Environment variables not configured (`"env": {}` is empty)
• Invalid URL format (must include `https://`)
• Incorrect credentials

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.

Testing

After configuring the environment variables as described in the "Configuration" section, you can manually test the server's authentication. The MCP Inspector (`npm run inspector`) is a useful tool for sending requests to the server.

1. Testing with API Key Authentication

1. Set the `METABASE_URL` and `METABASE_API_KEY` environment variables with your Metabase instance URL and a valid API key.

2. Ensure `METABASE_USERNAME` and `METABASE_PASSWORD` are unset or leave them, as the API key should take precedence.

3. Start the server: `npm run build && node build/index.js` (or use your chosen method for running the server, like via Claude Desktop config).

4. Check the server logs. You should see a message indicating that it's using API key authentication (e.g., "Using Metabase API Key for authentication.").

5. Using an MCP client or the MCP Inspector, try calling a tool, for example, `tools/call` with `{"name": "list_dashboards"}`.

6. Verify that the tool call is successful and you receive the expected data.

2. Testing with Username/Password Authentication (Fallback)

1. Ensure the `METABASE_API_KEY` environment variable is unset.

2. Set `METABASE_URL`, `METABASE_USERNAME`, and `METABASE_PASSWORD` with valid credentials for your Metabase instance.

3. Start the server.

4. Check the server logs. You should see a message indicating that it's using username/password authentication (e.g., "Using Metabase username/password for authentication." followed by "Authenticating with Metabase using username/password...").

5. Using an MCP client or the MCP Inspector, try calling the `list_dashboards` tool.

6. Verify that the tool call is successful.

3. Testing Authentication Failures

• Invalid API Key:

1. Set `METABASE_URL` and an invalid `METABASE_API_KEY`. Ensure `METABASE_USERNAME` and `METABASE_PASSWORD` variables are unset.

2. Start the server.

3. Attempt to call a tool (e.g., `list_dashboards`). The tool call should fail, and the server logs might indicate an authentication error from Metabase (e.g., "Metabase API error: Invalid X-API-Key").

• Invalid Username/Password:

1. Ensure `METABASE_API_KEY` is unset. Set `METABASE_URL` and invalid `METABASE_USERNAME`/`METABASE_PASSWORD`.

2. Start the server.

3. Attempt to call a tool. The tool call should fail due to failed session authentication. The server logs might show "Authentication failed" or "Failed to authenticate with Metabase".

• Missing Credentials:

1. Unset `METABASE_API_KEY`, `METABASE_USERNAME`, and `METABASE_PASSWORD`. Set only `METABASE_URL`.

2. Attempt to start the server.

3. The server should fail to start and log an error message stating that authentication credentials (either API key or username/password) are required (e.g., "Either (METABASE_URL and METABASE_API_KEY) or (METABASE_URL, METABASE_USERNAME, and METABASE_PASSWORD) environment variables are required").