Metabase Analytics Connector (MAC) Server 💎

This repository details a high-throughput Model Context Protocol (MCP) intermediary server for Metabase, engineered using the FastMCP framework and Python. This server bridges AI decision-makers (such as Claude or Cursor) directly to your Metabase environment, unlocking sophisticated data visualization and reporting functionality.

✨ Core Capabilities

Data Source Management

• Database Inventory: Enumerate all registered Metabase data repositories.
• Schema Exploration: Survey tables, including their metadata and contextual descriptions.
• Attribute Deep Dive: Acquire comprehensive details on table fields/columns, featuring intelligent pagination controls.

Insight Generation & Querying

• SQL Dispatch: Execute raw Structured Query Language (SQL) statements, with support for dynamic parameter substitution.
• Asset Execution: Invoke, formulate, and manage existing Metabase analytical assets (cards/questions).
• Organizational Structuring: Provision and maintain named collections for improved asset governance.

Security & Access Control

• Key-Based Authorization: Secure interaction via Metabase's native API credential mechanism (highly favored).
• Credential Handshake: Support for traditional email and password authentication fallback.
• Secret Handling: Secure management of sensitive configuration parameters using environment variable injection (.env).

🚀 Initialization Guide

Preconditions

• A modern Python runtime (version 3.12 or newer).
• Accessible Metabase server instance with API permissions enabled.
• Utilization of the uv package manager is suggested over pip.

Installation Procedure

Utilizing uv (Recommended Approach)

bash

Install uv if it is not present

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

Clone the source repository

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

Install all required libraries

uv sync

Using pip

bash

Clone and resolve dependencies

git clone https://github.com/yourusername/metabase-mcp.git cd metabase-mcp pip install -r requirements.txt

⚙️ Operational Setup

Generate a local configuration file by duplicating the template:

bash cp .env.example .env

Configuration Variants

Variant 1: API Credential Mode (Preferred)

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

Variant 2: Login Credential Mode

env METABASE_URL=https://your-metabase-instance.com METABASE_USER_EMAIL=your-account@example.com METABASE_PASSWORD=your-secure-password

Supplementary Settings: Transport Interface Tuning

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

💻 Runtime Execution

Launching the Server

bash

Standard Input/Output transport (Default binding)

uv run python server.py

Server-Sent Events (SSE) transport (Binds to HOST/PORT defaults)

uv run python server.py --sse

Standard HTTP transport (Binds to HOST/PORT defaults)

uv run python server.py --http

Specifying custom network parameters via environment variables

HOST=localhost PORT=9000 uv run python server.py --sse HOST=192.168.1.100 PORT=8080 uv run python server.py --http

Making environment settings permanent for the session

export HOST=localhost export PORT=9000 uv run python server.py --sse

FastMCP CLI Integration

bash

Execute using the FastMCP runner

fastmcp run server.py

Register the service for the Claude Desktop environment

fastmcp install server.py -n "Metabase Analyst"

Cursor IDE Configuration

I/O Stream Binding (Default)

bash uv run python scripts/install-cursor.py

SSE Transport Setup

bash

Installation for SSE transport, default port 8000

uv run python scripts/install-cursor.py --sse
uv run python scripts/install-cursor.py --sse 9000 # Custom port

Alternatively, use the dedicated SSE provisioning script

uv run python scripts/install-cursor-sse.py # Port 8000 uv run python scripts/install-cursor-sse.py 9000 # Custom port

Crucial Note for SSE: The server must be operational before Cursor attempts connection: bash uv run python server.py --sse 8000

Claude Desktop Integration

Once uv sync is complete, locate the Python binary at /path/to/repo/.venv/bin/python. Modify or append to your configuration file at ~/Library/Application\ Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "metabase-connector-server": { "command": "/path/to/repo/.venv/bin/python", "args": ["/path/to/repo/server.py"] } } }

🛠️ Exposed Functions

Data Source Utilities

Function	Purpose
list_databases	Retrieves a catalog of all available Metabase repositories
list_tables	Fetches schema metadata for tables within a specified repository
get_table_fields	Details the attributes/columns associated with a target table

Query Execution Modules

Function	Purpose
execute_query	Runs direct SQL commands, supporting argument injection
execute_card	Triggers the execution of pre-saved Metabase analytical assets

Asset Governance

Function	Purpose
list_cards	Generates a manifest of existing analytical visualizations
create_card	Defines and saves novel visualizations based on SQL input

Organizational Structuring

Function	Purpose
list_collections	Browses the hierarchical grouping structures
create_collection	Establishes new logical groupings for asset placement

Transport Mechanisms

The server supports three distinct communication channels:

• STDIO (Default): Optimized for local execution within development environments (Cursor, Claude Desktop).
• SSE: Utilizes Server-Sent Events, suitable for persistent, unidirectional data streams in web interfaces.
• HTTP: Standard request/response protocol for general API interactions.

bash uv run python server.py # STDIO (Default channel) uv run python server.py --sse # SSE (Hosts on 0.0.0.0:8000 by default) uv run python server.py --http # HTTP (Hosts on 0.0.0.0:8000 by default) HOST=localhost PORT=9000 uv run python server.py --sse # Customized network endpoints

🧪 Development Lifecycle

Environment Preparation

bash

Install core libraries plus development tools

uv sync --group dev

Alternative using pip

pip install -r requirements-dev.txt

Code Hygiene Checks

bash

Execute static analysis and error checking

uv run ruff check .

Apply automatic code formatting standards

uv run ruff format .

Perform static type verification

uv run mypy server.py

Run the complete test suite

uv run pytest -v

Execute tests while generating a detailed coverage report

uv run pytest --cov=server --cov-report=html

Health Validation

bash

Verify the server environment is correctly established

uv run python scripts/validate.py

📚 Operational Illustrations

Query Execution Samples

python

Obtain the full inventory of data sources

dbs = await list_databases()

Execute a filtered SQL retrieval

query_output = await execute_query( database_id=1, query="SELECT user_id, email FROM registered_users WHERE last_login > '2023-01-01'" )

Fabricate a new analytical visualization and execute it immediately

new_asset = await create_card( name="Q1 2024 Engagement Summary", database_id=1, query="SELECT SUM(activity_count) FROM daily_metrics WHERE quarter = 'Q1'", collection_id=2 )

Example File Locations

• examples/bootstrapping.py - Initial setup demonstration.
• examples/workflows.py - Showcase of sequential tool usage.
• examples/sse-streamer.py - Demonstration of the SSE transport mechanism.

📁 Repository Structure Map

metabase-mcp/ ├── server.py # Primary MCP service core logic ├── pyproject.toml # Project manifest and dependency declaration ├── .env.example # Template file for configuration variables ├── scripts/ │ ├── install-cursor.py # Script for Cursor integration via I/O │ ├── install-cursor-sse.py # Script for Cursor integration via SSE │ └── validate.py # Utility for environment health checks ├── examples/ # Sample code snippets ├── tests/ # Unit and integration test suite └── docs/ # Supplemental explanatory documents

🤝 Collaboration

We welcome external contributions! Kindly submit any improvements via a formal Pull Request.

📄 Licensing

This project is distributed under the MIT License; consult the LICENSE file for specifics.

🔗 Relevant References

• FastMCP Framework Documentation
• Model Context Protocol Specification
• Metabase Official API Reference