metabase-mcp-server

📊 Metabase MCP Server

📚 Table of Contents

1. What is this tool about?
2. Video Walkthrough
3. Architecture Diagram
4. Getting Started
   • Set Up Metabase
   • Install Required Software
   • Clone or Download the Repository
   • Install uv Package Manager
   • Create a Virtual Environment
   • Install Requirements
   • Configure Your .env
   • Connect to Your AI Client
5. Available Tools
6. Example Prompts to Try
7. 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-compatible AI 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 Required Software

Make sure the following software is installed and available in your system path:

• Python 3.11+ – Required to run the MCP server backend. Download Python

• Node.js – Required for running auxiliary MCP components or inspectors. Download Node.js

• Any MCP-compatible AI client – Example: Claude Desktop. Download Claude Desktop

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 uv Package Manager

Install uv using:

pip install uv

5. Create a Virtual Environment

uv venv .venv

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

6. Install Requirements

uv pip install -r requirements.txt

7. Configure Your .env

Create a .env file and add:

METABASE_URL=http://127.0.0.1:3000
METABASE_API_KEY=mb_xxx_your_api_key

8. Connect to Your AI Client

If you are using Claude Desktop, you need to modify your claude_desktop_config.json file.

Windows Path:

C:\Users\<YOUR_USERNAME>\AppData\Roaming\Claude\claude_desktop_config.json

macOS Path:

~/Library/Application Support/Claude/claude_desktop_config.json

Inside the config file, add:

{
  "mcpServers": {
    "metabase": {
      "command": "FULL_PATH\\metabase-mcp-server\\.venv\\Scripts\\python.exe",
      "args": ["FULL_PATH\\metabase-mcp-server\\src\\metabase_mcp_server.py"]
    }
  }
}

Important Notes

• Replace FULL_PATH with the actual location of your project directory.

• After saving the changes, restart Claude Desktop to apply the new configuration.

• The command and args paths depend on your operating system.

Windows Example:

"command": "FULL_PATH\\metabase-mcp-server\\.venv\\Scripts\\python.exe",
"args": ["FULL_PATH\\metabase-mcp-server\\src\\metabase_mcp_server.py"]

macOS/Linux Example:

"command": "FULL_PATH/metabase-mcp-server/.venv/bin/python",
"args": ["FULL_PATH/metabase-mcp-server/src/metabase_mcp_server.py"]

Key Differences:

• Windows uses backslashes \\ and .exe files.
• macOS/Linux uses forward slashes / and no .exe.

Make sure to match the correct format based on your OS to avoid errors.

Note:
For other AI clients, configure them similarly by setting the correct command to your Python executable and args to your MCP Server script path, based on your operating system.

---

🔧 Available Tools

---

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

---

📜 License

This project is licensed under the Apache License 2.0.

You can find the full license text in the file.

---