📊 Metabase MCP Server by CW-Codewalnut - MCP Server

📊 Metabase MCP Server

📚 Table of Contents

😊 What is this tool about?

Metabase MCP Server is a backend integration layer that connects your Metabase instance with AI assistants using the Model Context Protocol (MCP). This allows business leaders, product managers and analysts to interact with business intelligence assets like dashboards and charts using natural language—through any MCP client (e.g., Claude Desktop).

Instead of navigating through menus or constructing SQL queries manually, you can:

You can ask a question and get an instant insight.
Generate dashboards and charts by describing what you want.
Manage user access and database connections through simple instructions.

This project makes Metabase not just a dashboarding tool—but a conversational, intelligent business assistant.

🎥 Video Walkthrough

Watch this video to see the Metabase MCP Server in action:

📐 Architecture Diagram

🚀 Getting Started

1. Set Up Metabase (If you haven't already)

Follow the official Metabase installation guide: Metabase Docs

2. Install uv Package Manager

Install uv which includes Python and package management:

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or install via package managers:

# macOS
brew install uv

# Windows (via Scoop)
scoop install uv

# Windows (via Chocolatey)
choco install uv

For more information about uv installation and usage, please visit the official documentation: https://docs.astral.sh/uv/getting-started/installation/

3. Clone or Download the Repository

You need to get this tool onto your computer. You can either download it manually or use Git. Open your computer's Terminal (Mac) or Command Prompt (Windows). Navigate to the folder where you unzipped the files or want to clone the project:

# Example (replace with your actual path):
cd ~/Downloads/metabase-mcp-server-dev

Option 1: Download ZIP

Go to the GitHub repository
Click the green "Code" button
Select "Download ZIP"
Unzip the downloaded file to a location like your Documents folder

Option 2: Use Git If you're familiar with Git, run this in your terminal:

git clone https://github.com/codewalnut/metabase-mcp-server.git
cd metabase-mcp-server

4. Install dependencies

This command will automatically:

Install the required Python version (if not already available)
Create a virtual environment for the project
Install all necessary packages and dependencies

uv sync

5. Configure Your Credentials

You have three options to configure your Metabase credentials for the MCP Server:

Option 1: Using a .env file (Recommended) Create a .env file in the project root:

METABASE_URL=http://localhost:3000
METABASE_API_KEY=mb_xxx_your_key
PORT=3200
HOST=localhost
TRANSPORT=streamable-http
LOG_LEVEL=DEBUG

Option 2: Using command-line arguments Pass configuration directly via command line:

 uv run src/metabase_mcp_server.py --metabase-url http://localhost:3000 --metabase-api-key "YOUR_API_KEY" --port 3200 --host localhost --transport streamable-http --log-level DEBUG

Option 3: Using environment variables in MCP client config Configure directly in your MCP client without a .env file (see examples below).

{
  "mcpServers": {
    "metabase": {
      "type": "stdio"
      "command": "uv",
      "args": ["run", "C:\\Users\\YourName\\Projects\\metabase-mcp-server\\src\\metabase_mcp_server.py"],
      "env": {
        METABASE_URL=http://localhost:3000
        METABASE_API_KEY=mb_xxx_your_key
        PORT=3200
        HOST=localhost
        TRANSPORT=streamable-http
        LOG_LEVEL=DEBUG
      }
    }
  }
}

6. Connect to Your MCP client

Choose your preferred MCP clients like Claude Desktop app, Claude Code, Cursor, Windsurf etc., and add the Metabase MCP server in their respective configuration files. All MCP clients follow a similar configuration pattern.

Configuration Examples

For stdio transport (recommended for local MCP server):

Windows:

{
  "mcpServers": {
    "metabase": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "C:\\Users\\YourName\\Projects\\metabase-mcp-server\\src\\metabase_mcp_server.py""]
    }
  }
}

Mac:

{
  "mcpServers": {
    "metabase": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "/Users/YourName/Projects/metabase-mcp-server/src/metabase_mcp_server.py"]
    }
  }
}

Key Differences:

Windows uses backslashes \\ in paths
macOS/Linux uses forward slashes / in paths
Make sure to match the correct format based on your OS to avoid errors

Important Notes:

Replace FULL_PATH with the actual absolute path to your project directory
After saving configuration changes, restart your MCP client to apply the new settings
For project-specific tools in Cursor, create a .cursor/mcp.json file in your project directory
For global tools in Cursor, create a ~/.cursor/mcp.json file in your home directory

For streamable-http transport (recommended for remote MCP server):

{
  "mcpServers": {
    "metabase": {
      "type": "streamable-http",
      "url": "http://localhost:3200/mcp/"
    }
  }
}

Compatible MCP clients

Click on any client to visit their official MCP setup documentation:

Client	Official MCP Documentation
	Anthropic's official MCP guide for Claude Desktop
	Official Claude Code MCP setup documentation
	Cursor's official MCP configuration guide
	Windsurf official MCP setup documentation
	Cline's official MCP quickstart guide
	VS Code Copilot MCP server configuration

Once you have added the configuration, the MCP server should be visible in your MCP client.

🔧 Configuration Options

The Metabase MCP Server supports flexible configuration through environment variables, command-line arguments, or a combination of both.

Environment Variables

Variable	Description	Default Value	Example
`METABASE_URL`	Your Metabase instance URL	Required	`http://127.0.0.1:3000`
`METABASE_API_KEY`	Your Metabase API key	Required	`mb_xxx_your_api_key`
`TRANSPORT`	Transport protocol	`streamable-http`	`stdio`, `streamable-http`
`HOST`	Host for HTTP transports	`localhost`	`0.0.0.0`, `127.0.0.1`
`PORT`	Port for HTTP transports	`3200`	`8080`, `9000`
`LOG_LEVEL`	Logging level	`INFO`	`DEBUG`, `WARNING`, `ERROR`

Command-line Arguments

Argument	Description	Default Value
`--metabase-url`	Metabase instance URL	Required
`--metabase-api-key`	Metabase API key	Required
`--transport`	Transport protocol	`streamable-http`
`--host`	Host for HTTP transports	`localhost`
`--port`	Port for HTTP transports	`3200`
`--log-level`	Logging verbosity level	`INFO`

Transport Protocols

Protocol	Description	Use Case
stdio	Standard input/output communication	Best for local integrations (Claude Desktop, Cursor, etc.)
streamable-http	HTTP-based streaming protocol	Ideal for remote deployments and web-based integrations
sse	Server-Sent Events over HTTP	⚠️ Deprecated - Not recommended for new setups

Configuration Priority

Configuration values are applied in the following priority order (highest to lowest):

Command-line arguments (overrides everything)
Environment variables (overrides defaults)
Default values

Complete Command Examples

uv run src/metabase_mcp_server.py --transport streamable-http --host localhost --port 3200 --metabase-url http://127.0.0.1:3000 --metabase-api-key mb_xxx_your_key

Note: You don't need to pass every parameter when running the server. However, you must provide the Metabase URL and API key. Any parameters not specified will use their default values as shown above.

🔑 Getting Your Metabase API Key

To get your Metabase API key:

Log into your Metabase instance
Click on your profile picture (top-right corner)
Select "Account settings"
Navigate to the "API Keys" tab
Click "Create API Key"
Give your key a descriptive name (e.g., "MCP Server Key")
Copy the generated key (starts with mb_)

⚠️ Important: Store your API key securely and never commit it to version control. The key provides full access to your Metabase instance.

📂 DXT File Support

You no longer need to go through the steps of cloning the repository and setting up the environment. Simply follow the steps below to install the Metabase MCP Server in your Cloude Desktop App:

Download the DXT File
Check the link below to download the latest DXT file directly:
Open the Cloude Desktop App
Once you have the file, open the Cloude Desktop App on your system.
Navigate to Extensions Settings
In the Cloude Desktop App:
- Go to Files → Settings → Extensions
- Then click on Advanced Settings.
Select the DXT File
In the Advanced Settings section, click on Choose File, select the downloaded DXT file.
Enter the Required Details
After slecting the DXT file, a prompt will appear asking you to fill in the required details:
- Metabase URL: Enter your Metabase server URL.
- API Key: Add the relevant API key for authentication.
Complete the Setup
After entering the necessary details, click Save to apply the configuration.

That's it! The Metabase MCP Server is now installed and ready to use in your Cloude Desktop App.

How to Create Your Own DXT File

If you want to create your own DXT file, please visit the Official Guide:
Creating Your Own DXT File

🚀 Remote Deployment

For production use or team collaboration, you can deploy the Metabase MCP Server remotely. We use this approach internally at Codewalnut.

Docker Deployment

We've included Docker configuration files to make remote deployment straightforward.

Quick Start with Docker

# Build the Docker image
docker build -t metabase-mcp-server .

# Run with environment variables
docker run -d \
  -p 3200:3200 \
  -e METABASE_URL="http://your-metabase-instance.com" \
  -e METABASE_API_KEY="mb_xxx_your_api_key" \
  metabase-mcp-server

Docker Compose (Recommended)

version: '3.8'
services:
  metabase-mcp:
    build: .
    ports:
      - "3200:3200"
    environment:
      - METABASE_URL=http://your-metabase-instance.com
      - METABASE_API_KEY=mb_xxx_your_api_key
      ##- PORT=3200
      ##- HOST=localhost
      ##- TRANSPORT=streamable-http
      ##- LOG_LEVEL=DEBUG
    restart: unless-stopped

Connecting to Remote MCP Server

Once deployed, configure your MCP clients to connect to the remote server:

{
  "mcpServers": {
    "metabase": {
      "type": "streamable-http",
      "url": "http://server-ip:3200/mcp/"
    }
  }
}

Deployment Options

Cloud Providers: AWS ECS, Google Cloud Run, Azure Container Instances
VPS/Dedicated Servers: DigitalOcean, Linode, Vultr
Container Platforms: Kubernetes, Docker Swarm
Platform-as-a-Service: Railway, Render, Fly.io

Security Considerations

Use HTTPS in production environments
Implement proper firewall rules
Consider VPN access for sensitive business data
Regularly rotate API keys
Monitor access logs

Need Help with Deployment?

Our team at CodeWalnut offers deployment and consulting services. Contact us for enterprise-grade setup and support.

🔍 Debugging with MCP Inspector

To debug and test your Metabase MCP Server setup, you can use the official MCP Inspector tool.

Prerequisites

First, install Node.js if you haven't already:

Download from: nodejs.org

Or install via package manager:

# macOS
brew install node

# Windows (via Chocolatey)
choco install nodejs

# Windows (via Scoop)
scoop install nodejs

Install and Run MCP Inspector

# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Run the inspector with your Metabase MCP Server
npx @modelcontextprotocol/inspector uv run FULL_PATH/metabase-mcp-server/src/metabase_mcp_server.py

Using MCP Inspector

The MCP Inspector provides:

Real-time tool testing - Execute MCP tools directly from the web interface
Request/Response monitoring - See exactly what data is being sent and received
Error debugging - Identify configuration or API issues quickly
Schema validation - Verify that your tools are properly defined

Once running, open your browser to http://localhost:5173 to access the inspector interface.

Common Debugging Scenarios

Connection issues - Verify your Metabase URL and API key
Permission errors - Check if your API key has the required permissions

🔧 Available Tools

Function	Description
Collection Operations
`get_metabase_collection`	Get a collection by ID
`create_metabase_collection`	Create a new collection
`update_metabase_collection`	Update collection metadata
`delete_metabase_collection`	Delete a collection
Chart (Card) Operations
`get_metabase_cards`	List all charts
`get_card_query_results`	Get results from a chart query
`create_metabase_card`	Create a new chart
`update_metabase_card`	Update an existing chart
`delete_metabase_card`	Delete a chart
Dashboard Operations
`get_metabase_dashboards`	List all dashboards
`get_dashboard_by_id`	Get a dashboard by ID
`get_dashboard_cards`	Get cards in a dashboard
`get_dashboard_items`	Get all dashboard items
`create_metabase_dashboard`	Create a dashboard
`update_metabase_dashboard`	Update a dashboard
`delete_metabase_dashboard`	Delete a dashboard
`copy_metabase_dashboard`	Create a copy of an existing dashboard
Database Operations
`get_metabase_databases`	List databases
`create_metabase_database`	Create a new database connection
`update_metabase_database`	Update a database connection
`delete_metabase_database`	Delete a database connection
User Operations
`get_metabase_users`	List all users
`get_metabase_current_user`	Get current user details
`create_metabase_user`	Create a new user
`update_metabase_user`	Update user info
`delete_metabase_user`	Delete a user
Group Operations
`get_metabase_groups`	List user groups
`create_metabase_group`	Create a user group
`delete_metabase_group`	Delete a user group
SQL Operations
`execute_sql_query`	Execute a native SQL query

🧪 Example Prompts to Try

Create a dashboard called 'Flight Overview' with a bar chart showing flights by destination city.
Run SQL: SELECT origin, destination, COUNT(*) FROM flights GROUP BY origin, destination LIMIT 10.
Create a card displaying total bookings last month grouped by region.
Delete the chart named 'Abandoned Queries'.
Update the dashboard 'Sales KPIs' to include a new revenue card.
Show all users in the 'Admin' group.
Create a new group called 'Finance Analysts'.
Connect to a Supabase database and list all tables.