Metabase Mcp Server

📊 Metabase MCP Server

📚 Table of Contents

1. [What is this tool about?](#-what-is-this-tool-about)
2. [Video Walkthrough](#-video-walkthrough)
3. [Architecture Diagram](#-architecture-diagram)
4. [Getting Started](#-getting-started)

• [Set Up Metabase](#1-set-up-metabase-if-you-havent-already)
• [Install uv Package Manager](#2-install-uv-package-manager)
• [Clone or Download the Repository](#3-clone-or-download-the-repository)
• [Install dependencies](#4-install-dependencies)
• [Configure Your Credentials](#5-configure-your-credentials)
• [Connect to Your MCP client](#6-connect-to-your-mcp-client)

1. [Configuration Options](#-configuration-options)
2. [Getting Your Metabase API Key](#-getting-your-metabase-api-key)
3. [DXT File Support](#-dxt-file-support)
4. [How to Create Your Own DXT File](#how-to-create-your-own-dxt-file)
5. [Remote Deployment](#-remote-deployment)
6. [Debugging with MCP Inspector](#-debugging-with-mcp-inspector)
7. [Available Tools](#-available-tools)
8. [Example Prompts to Try](#-example-prompts-to-try)
9. [Connect with Us](#-connect-with-us)
10. [License](#-license)

---

😊 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:

[](https://youtu.be/1-86KuNwbdE?feature=shared")

---

📐 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

1. Go to the GitHub repository
2. Click the green "Code" button
3. Select "Download ZIP"
4. 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": "C:\\Users\\YourName\\Projects\\metabase-mcp-server\\.venv\\Scripts\\python.exe",
      "args": [
        "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": "C:\\Users\\YourName\\Projects\\metabase-mcp-server\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\YourName\\Projects\\metabase-mcp-server\\src\\metabase_mcp_server.py"
      ]
    }
  }
}

Mac:

{
  "mcpServers": {
    "metabase": {
      "type": "stdio",
      "command": "/Users/YourName/Projects/metabase-mcp-server/venv/Scripts/python",
      "args": [
        "/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 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | | [](https://support.anthropic.com/en/articles/10949351-getting-started-with-model-context-protocol-mcp-on-claude-for-desktop) | Anthropic's official MCP guide for Claude Desktop | | [](https://docs.anthropic.com/en/docs/claude-code/mcp) | Official Claude Code MCP setup documentation | | [](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers) | Cursor's official MCP configuration guide | | [](https://docs.windsurf.com/windsurf/mcp) | Windsurf official MCP setup documentation | | [](https://docs.cline.bot/mcp-servers/mcp-quickstart) | Cline's official MCP quickstart guide | | [](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server-to-your-workspace) | 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):

1. Command-line arguments (overrides everything)
2. Environment variables (overrides defaults)
3. 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:

1. Log into your Metabase instance
2. Click on your profile picture (top-right corner)
3. Select "Account settings"
4. Navigate to the "API Keys" tab
5. Click "Create API Key"
6. Give your key a descriptive name (e.g., "MCP Server Key")
7. 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:

1. Download the DXT File

Check the link below to download the latest DXT file directly: [Download DXT File](./metabase-mcp-server.dxt)

1. Open the Cloude Desktop App

Once you have the file, open the Cloude Desktop App on your system.

1. Navigate to Extensions Settings

In the Cloude Desktop App:

• Go to Files → Settings → Extensions
• Then click on Advanced Settings.

1. Select the DXT File

In the Advanced Settings section, click on Choose File, select the downloaded DXT file.

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

1. 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](#-connect-with-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](https://nodejs.org/en/dow

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: CW-Codewalnut
• Source: CW-Codewalnut/metabase-mcp-server
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.