Connect Claude to Metabase with MCP

Most BI workflows follow the same pattern: open Metabase, find the right dashboard, run a query, export results, paste into a doc. It works, but it breaks flow. Every question requires switching context and knowing exactly where to look.

The Model Context Protocol (MCP) changes that equation. By connecting Claude directly to your Metabase instance, you can query dashboards, execute SQL, inspect table schemas, and create questions using natural language, without leaving your AI assistant. We built the Metabase MCP Server to make that integration production-ready.

This guide covers what MCP is, how the Metabase server works, and how to get it running in under five minutes.

What Is MCP?

Model Context Protocol (MCP) is an open standard introduced by Anthropic that lets AI assistants connect to external tools and data sources through a structured interface. Think of it as a USB-C port for AI, any MCP-compatible client (Claude Desktop, Cursor, Windsurf) can connect to any MCP-compatible server.

Instead of uploading CSV exports or copy-pasting query results into a chat window, MCP gives the AI direct, live access to your systems. The AI calls tools, reads responses, and reasons over real data, in one session.

What the Metabase MCP Server Does

The server exposes 96 tools across six domains, giving an AI assistant full operational coverage of a Metabase instance.

A practical example: ask Claude "What are the top 10 products by revenue this month?" and it will call execute_query against your database, format the results, and summarize them, no dashboard required.

Prerequisites

• Metabase v0.46.x or later (Cloud or self-hosted)
• A Metabase API key (preferred) or username/password credentials
• Claude Desktop, Cursor, or any MCP-compatible client
• Node.js 18+ (for npx install)

Setup in 3 Steps

Step 1 - Get your Metabase API Key

In Metabase, go to Account Settings → API Keys and create a new key with appropriate permissions. Copy the key, you'll need it in the next step.

For self-hosted instances, API key support requires Metabase v0.48.x or later. On older versions, use username/password authentication instead.

Step 2 - Add the server to your MCP client config

Claude Desktop config file locations:

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

Add the following block:

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@easecloudio/mcp-metabase-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

Save the file and restart Claude Desktop.

Step 3 - Verify the connection

Open Claude Desktop and ask: "List my Metabase dashboards."

If the server is connected, Claude will call list_dashboards and return your dashboard names. That confirms the integration is working.

Controlling Tool Surface Area

By default, the server exposes all 96 tools. For most production setups, you'll want to restrict this. The TOOL_MODE environment variable controls which tools are available:

"env": {
  "METABASE_URL": "https://your-metabase-instance.com",
  "METABASE_API_KEY": "your_metabase_api_key",
  "TOOL_MODE": "read"
}

For analyst workflows, read mode is the right default. It prevents the AI from modifying dashboards or deleting content while still allowing full query and inspection access.

Docker Deployment

For teams that prefer containerized deployments or need the server running as a persistent process:

docker run -it --rm \
  -e METABASE_URL=https://your-metabase-instance.com \
  -e METABASE_API_KEY=your_metabase_api_key \
  -e TOOL_MODE=read \
  $(docker build -q .)

The Dockerfile is included in the repository and builds a minimal Node.js image. This approach works well when you need the MCP server available to multiple clients on the same network.

The SQL-to-MBQL Conversion Workflow

One of the more powerful features is the schema cache, which enables conversion of native SQL questions into interactive Metabase questions (MBQL format). This is not something Metabase exposes through its REST API, the server handles it by caching field IDs locally.

The workflow runs in four steps:

1. Call get_card to extract the SQL and database_id from an existing question
2. Call get_schema_cache to retrieve tables and field IDs for the target database
3. Claude translates the SQL into MBQL using the cached field IDs
4. Call create_card to save the new interactive question

The cache lives at ~/.easecloud/metabase-mcp/cache/ with a 24-hour TTL, scoped per Metabase instance. Call refresh_schema_cache to force a refresh after schema changes.

What You Can Ask Claude Once Connected

A few examples of what becomes possible after setup:

• "Show me all dashboards in the Marketing collection"
• "Run the Monthly Revenue question and summarize the trend"
• "Which tables in the production database have more than 1M rows?"
• "Create a new question that counts orders by status for the last 30 days"
• "Compare this week's signups to last week"

The server handles authentication, pagination, and error formatting transparently, Claude just sees structured results.

Supported Metabase Versions

Get Started

The server is open source and available on npm:

npx @easecloudio/mcp-metabase-server

Source, issues, and contribution guidelines are on GitHub: github.com/easecloudio/mcp-metabase-server

If your team is adopting Metabase at scale or building AI-assisted analytics workflows, get in touch with EaseCloud. We provide consulting, customization, and managed support for enterprise Metabase deployments.