metabase_mcp

Postergully/metabase_mcp

3.2

If you are the rightful owner of metabase_mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A standalone Model Context Protocol (MCP) server for seamless Metabase integration with Claude Code, Cursor, and other MCP-compatible AI assistants.

Tools
9
Resources
0
Prompts
0

📊 Metabase MCP Server

A standalone Model Context Protocol (MCP) server for seamless Metabase integration with Claude Code, Cursor, and other MCP-compatible AI assistants.

🌟 Stdio Mode Support

This server operates in stdio mode for local MCP integration with Claude Desktop, Cursor, and other MCP-compatible AI assistants.

Quick Add to Claude (Stdio Mode)

claude mcp add metabase node /Applications/Metabase-mcp-server/build/index.js \
  --env METABASE_URL=https://your-metabase-instance.com \
  --env METABASE_API_KEY=your_api_key \
  --env SERVER_MODE=stdio

🚀 Quick Start

Prerequisites

  • Node.js 18+ installed
  • Active Metabase instance with API access
  • Claude Desktop or other MCP-compatible client

Installation & Setup

  1. Navigate to server directory

    cd /Applications/Metabase-mcp-server

  2. Install dependencies

    npm install

  3. Configure environment

    cp .env.example .env
# Edit .env with your Metabase credentials

  4. Build the server

    npm run build

  5. Test the server

    node build/index.js

🔧 Configuration

Environment Variables

The server requires configuration via environment variables. Copy .env.example to .env and update with your values:

# Required: Metabase instance URL
METABASE_URL=https://your-metabase-instance.com

# Preferred: API Key authentication
METABASE_API_KEY=your_metabase_api_key

# Fallback: Username/Password authentication
METABASE_USERNAME=your_username@example.com
METABASE_PASSWORD=your_password

# Optional: Direct database access
METABASE_DATABASE_USERNAME=db_username
METABASE_DATABASE_PASSWORD=db_password
METABASE_DATABASE_HOST=your_database_host

# Optional: Default dashboard for operations
DEFAULT_DASHBOARD_ID=123

Default Dashboard Support: When DEFAULT_DASHBOARD_ID is configured, all dashboard-related tools will use this dashboard ID by default when no dashboard_id parameter is provided. This makes operations more convenient while maintaining backward compatibility.

Authentication Methods

The server supports two authentication methods (in order of preference):

  1. API Key (Recommended)

    • Get from: Metabase Admin → Settings → Authentication → API Keys
    • More secure and doesn't require password storage
    • Set METABASE_API_KEY environment variable

  2. Username/Password (Fallback)

    • Uses your regular Metabase login credentials
    • Set METABASE_USERNAME and METABASE_PASSWORD environment variables
    • Only used if METABASE_API_KEY is not provided

🔌 Integration with Claude Code

Add to Claude Desktop Configuration

  1. Open Claude Desktop configuration

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%/Claude/claude_desktop_config.json

  2. Add MCP server configuration

    {
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/Applications/Metabase-mcp-server/build/index.js"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_api_key_here"
      }
    }
  }
}

  3. Restart Claude Desktop

Verification

After configuration, you should see the Metabase MCP server appear in Claude Code's available tools. Test with:

"List all dashboards in Metabase"
"Show me cards in dashboard ID 1"
"Execute card ID 39 and show results"

🛠 Available Tools

The MCP server provides the following tools for AI assistants:

  • 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

Dashboard Operations

  • list_dashboards - List all dashboards with pagination
  • get_dashboard - Get specific dashboard details
  • get_dashboard_cards - Get all cards in a dashboard
  • add_card_to_dashboard - Add a card to a dashboard with intelligent positioning

Card/Question Operations

  • list_cards - List all questions/cards with pagination
  • get_card - Get specific card details by ID
  • execute_card - Execute a card and get results

Database Operations

  • list_databases - List all connected databases
  • execute_query - Execute SQL queries against databases

🎯 Enhanced Features (Latest Updates)

  • Intelligent Card Sizing - Automatically determines optimal card dimensions based on chart type
  • Smart Positioning - Prevents card overlaps with intelligent grid placement
  • Visualization Preservation - Maintains original card settings when adding to dashboards
  • Pagination Support - Handles large datasets with configurable limits (default: 50, max: 200)
  • Comprehensive Validation - Pre and post-operation validation with detailed error reporting
  • Token Limit Management - Prevents MCP response size limits (25,000 tokens) with intelligent pagination

Configuration

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

  1. API Key (Preferred):

    • METABASE_URL: The URL of your Metabase instance (e.g., https://your-metabase-instance.com).
    • METABASE_API_KEY: Your Metabase API key.

  2. Username/Password (Fallback):

    • METABASE_URL: The URL of your Metabase instance.
    • METABASE_USERNAME: Your Metabase username.
    • METABASE_PASSWORD: Your Metabase password.

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 (Local Development)

# 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.

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").