Metabase MCP server for AI agents

This MCP server integrates your Metabase analytics platform with AI assistants like Claude, allowing them to interact directly with your data through a structured interface. It acts as a bridge between conversational AI and your analytics data, providing access to dashboards, saved questions, and custom queries.

Installation

Prerequisites

Node.js 18.0.0 or higher
An active Metabase instance with appropriate credentials

Basic Setup

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

For development with automatic rebuilding when changes are detected:

npm run watch

Docker Setup

You can also run the server as a containerized application:

# 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

Configuration

The server supports two authentication methods for connecting to your Metabase instance:

Option 1: Username and Password Authentication

# Required
METABASE_URL=https://your-metabase-instance.com
[email protected]
METABASE_PASSWORD=your_password

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

Option 2: API Key Authentication (Recommended for Production)

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

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

You can set these environment variables directly or use a .env file.

Integrating with Claude Desktop

To use this server with Claude Desktop, you'll need to edit the Claude configuration file:

MacOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: Edit %APPDATA%/Claude/claude_desktop_config.json

Add the server configuration as follows:

{
  "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": "[email protected]",
        "METABASE_PASSWORD": "your_password"
        // Or alternatively, use API key authentication
        // "METABASE_API_KEY": "your_api_key"
      }
    }
  }
}

Alternative: Using Smithery Hosted Version

You can also use the Smithery hosted version via npx with JSON configuration:

For API Key Authentication:

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

For Username and Password Authentication:

{
  "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\":\"[email protected]\"}"
      ]
    }
  }
}

Using the Server

Once configured, Claude can access the following tools to interact with your Metabase data:

list_dashboards: Retrieve all available dashboards
list_cards: Get all saved questions/cards
list_databases: View all connected database sources
execute_card: Run saved questions and retrieve results
get_dashboard_cards: Extract all cards from a specific dashboard
execute_query: Execute custom SQL queries against any connected database

Debugging

Since MCP servers communicate over stdio, you can use the MCP Inspector for debugging:

npm run inspector

This will provide a browser-based interface for monitoring requests and responses between Claude and your Metabase instance.

Security Best Practices

Use API key authentication for production environments
Keep your API keys and credentials secure
Consider using Docker secrets or environment variables instead of hardcoding credentials
Apply appropriate network security measures to restrict access to your Metabase instance

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.