Metabase MCP Plus

An enhanced Model Context Protocol (MCP) server for Metabase, enabling AI assistants like Claude, Cursor, and other MCP clients to query databases, execute SQL, manage dashboards, cards, and collections — all through natural language.

Quick Start

Using uvx (No Installation Required)

uvx metabase-mcp-plus

Using pip

pip install metabase-mcp-plus
metabase-mcp-plus

From Source

git clone https://github.com/schachan/metabase-mcp.git
cd metabase-mcp
uv sync
uv run python server.py

Configuration

Set environment variables directly or create a .env file:

cp .env.example .env

API Key Authentication (Recommended)

METABASE_URL=https://your-metabase-instance.com
METABASE_API_KEY=your-api-key-here

Email/Password Authentication

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

Optional: Custom Host/Port (SSE/HTTP transports)

HOST=localhost  # Default: 0.0.0.0
PORT=9000       # Default: 8000

Available Tools (22)

Database Operations (6 tools)

Tool	Description
`list_databases`	List all configured databases
`get_database`	Get details of a specific database
`list_tables`	Get all tables in a database with metadata
`get_table_fields`	Retrieve field/column information for a table
`list_database_schemas`	List all schemas in a database
`get_schema_tables`	Get tables within a specific schema

Query Operations (1 tool)

Tool	Description
`execute_query`	Execute native SQL queries with parameter support

Card / Question Management (6 tools)

Tool	Description
`list_cards`	List all saved questions/cards
`get_card`	Get details of a specific card
`execute_card`	Run a saved question and return results
`create_card`	Create a new question with a SQL query
`update_card`	Update an existing card's name, query, or collection
`archive_card`	Archive a card

Dashboard Management (5 tools)

Tool	Description
`list_dashboards`	List all dashboards
`get_dashboard`	Get full dashboard details including cards
`create_dashboard`	Create a new dashboard
`update_dashboard`	Update a dashboard's name, description, or cards
`delete_dashboard`	Delete a dashboard

Collection Management (3 tools)

Tool	Description
`list_collections`	Browse all collections
`get_collection_items`	List items within a collection
`create_collection`	Create a new collection

Search (1 tool)

Tool	Description
`search`	Search across cards, dashboards, collections, and tables

Transport Methods

metabase-mcp-plus                # STDIO (default, for IDE integration)
metabase-mcp-plus --sse          # Server-Sent Events
metabase-mcp-plus --http         # Streamable HTTP

Or from source:

uv run python server.py          # STDIO
uv run python server.py --sse    # SSE
uv run python server.py --http   # HTTP

IDE Integration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
    "mcpServers": {
        "metabase": {
            "command": "uvx",
            "args": ["metabase-mcp-plus"],
            "env": {
                "METABASE_URL": "https://your-metabase-instance.com",
                "METABASE_API_KEY": "your-api-key-here"
            }
        }
    }
}

Cursor

Add to your MCP settings (.cursor/mcp.json):

{
    "mcpServers": {
        "metabase": {
            "command": "uvx",
            "args": ["metabase-mcp-plus"],
            "env": {
                "METABASE_URL": "https://your-metabase-instance.com",
                "METABASE_API_KEY": "your-api-key-here"
            }
        }
    }
}

Project Structure

metabase-mcp/
├── server.py              # Entry point — CLI arg parsing and transport selection
├── app.py                 # FastMCP app setup, env loading, client instantiation
├── client.py              # MetabaseClient with auth, retry, and error handling
├── tools/
│   ├── __init__.py        # Registers all tool modules
│   ├── databases.py       # Database, table, schema, and field tools
│   ├── queries.py         # SQL query execution
│   ├── cards.py           # Card CRUD and execution
│   ├── dashboards.py      # Dashboard CRUD
│   ├── collections.py     # Collection browsing and creation
│   └── search.py          # Cross-entity search
├── tests/                 # Comprehensive test suite (95% coverage)
├── .github/workflows/
│   ├── ci.yml             # Lint + test on push/PR
│   └── publish.yml        # Release → PyPI + attach assets
├── RELEASING.md           # How to cut a release (trusted publisher setup)
└── pyproject.toml

Development

# Install with dev dependencies
uv sync --group dev

# Run linting and formatting
uv run ruff check .
uv run ruff format .

# Run tests with coverage
uv run pytest tests/ --cov=. --cov=tools --cov-report=term-missing -v

Architecture Highlights

Modular tools — each domain (databases, cards, dashboards, etc.) is a separate module
Automatic auth retry — expired session tokens are refreshed transparently on 401
Custom exceptions — MetabaseAPIError and MetabaseAuthError for typed error handling
Error handler decorator — @tool_error_handler eliminates boilerplate try/except across all 22 tools
Middleware stack — built-in error handling and logging middleware via FastMCP

Releases & PyPI

Publishing to PyPI is automated when you publish a GitHub Release (workflow .github/workflows/publish.yml): lint → test → build → attach wheels to the release → upload to PyPI (trusted publisher / OIDC).

See RELEASING.md for one-time PyPI + GitHub environment setup and the exact tag/version rules (v1.2.3 must match version = "1.2.3" in pyproject.toml).

License

MIT License — see LICENSE for details.

Metabase MCP Plus