Metabase

You run a Metabase MCP Server to let AI assistants query and interact with your Metabase analytics data. It exposes a set of tools to list dashboards, cards, databases, run saved questions, extract cards from dashboards, and execute custom SQL, all through a simple MCP interface.

How to use

Connect your MCP client to the Metabase MCP Server using one of the supported local (stdio) configurations or through a remote setup. Once connected, you can browse and retrieve Metabase resources, run saved questions, and execute custom queries. Use the available tools to list dashboards and cards, view all databases, or run a specific card with optional parameters. You can also fetch all cards from a particular dashboard for quick exploration and then run those cards against your databases.

How to install

Prerequisites you need before installation are straightforward.

# Prerequisites
- Node.js 18.0.0 or higher
- Access to a Metabase instance with credentials

# Install dependencies
npm install

# Build the project
npm run build

# Start the server (production)
npm start

# For development with auto-rebuild
npm run watch

Additional configuration and usage notes

Two authentication methods are supported to connect securely to Metabase:

Authentication options (examples)

Option 1: Username and Password Authentication requires your Metabase URL, user email, and password. You may optionally set a log level.

# 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

Authentication options (API key)

Option 2: API Key Authentication is recommended for production. You must provide the Metabase URL and an API key.

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

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

Claude Desktop integration (local development)

You can run the server locally and point Claude Desktop at it by editing the client configuration. This example shows the server path and environment variables you would provide to Claude Desktop.

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

API key and password examples for MCP runner

If you prefer using a command-line MCP runner (via a local CLI) you can pass a full JSON configuration to the runner. The following examples show both API key and username/password approaches.

# API Key Authentication example for MCP runner
{
  "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\":\"\"}"
      ]
    }
  }
}

# Username and Password Authentication example for MCP runner
{
  "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\"}"
      ]
    }
  }
}

Troubleshooting and debugging

MCP servers communicate over stdio. If you encounter issues, use the MCP Inspector to monitor requests and responses in a browser-based interface. Start the inspector with the provided debugging command in your project scripts.

Docker deployment

A Docker image is available for containerized deployment. Build and run with environment variables to point at your Metabase instance.

# 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

Security considerations

Use API keys for production, keep credentials secure, and consider using Docker secrets or environment variables to avoid hardcoding values. Limit network access to your Metabase instance to trusted clients.

Contributing

Contributions are welcome. If you have improvements or fixes, submit a pull request with your changes.

Available tools

list_dashboards

Retrieve all available dashboards in your Metabase instance.

list_cards

Get all saved questions/cards in Metabase.

list_databases

View all connected database sources.

execute_card

Run saved questions/cards and retrieve results with optional parameters.

get_dashboard_cards

Extract all cards from a specific dashboard.

execute_query

Execute custom SQL queries against any connected database.