Metabase MCP Service Adapter 🚀

This repository details a high-throughput Model Context Protocol (MCP) server engineered for Metabase integration, leveraging the FastMCP framework implemented in Python. This server facilitates sophisticated data interaction between large language models (like Claude or Cursor) and your Metabase deployment, unlocking comprehensive data exploration and visualization capabilities.

✨ Core Functionality Portfolio

Data Source Management

• Database Enumeration: Retrieve a catalog of all defined Metabase data sources.
• Schema Exploration: Discover available tables within a dataset, complete with descriptive metadata.
• Attribute Detailing: Obtain granular specifications for table fields/columns, featuring optimized pagination control.

Analytical & Querying Capabilities

• Raw SQL Dispatch: Execute direct SQL commands, supporting dynamic parameter injection.
• Card/Question Execution: Trigger saved Metabase analytical artifacts (cards).
• Organizational Structuring: Provision and manage content collections for better grouping.

Credential Handling & Access Control

• API Token Security (Preferred): Secure access utilizing Metabase API keys.
• Traditional Credentials: Fallback support for username/password authentication.
• Environment Isolation: Secure storage and loading of sensitive configuration via standard .env configuration files.

🚀 Rapid Deployment Guide

Prerequisites

1. Python interpreter, version 3.12 or newer.
2. A functional Metabase environment configured for API access.
3. The uv package manager is suggested over pip.

Installation Procedures

Utilizing uv (Recommended path)

bash

Install uv utility if absent

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

Resolve and install all dependencies

uv sync

Using pip

bash

Clone and install dependencies

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

⚙️ Setup and Initialization

Initialize the configuration file by copying the template:

bash cp .env.example .env

Configuration Variables

Method A: API Key Authentication (Best Practice)

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

Method B: Email and Password

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

Network Overrides (Optional)

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

Execution Workflow

Launching the Service Endpoint

bash

Standard Input/Output stream mode (default for desktop clients)

uv run python server.py

Server-Sent Events (SSE) stream mode (defaults to 0.0.0.0:8000)

uv run python server.py --sse

Standard HTTP request/response mode (defaults to 0.0.0.0:8000)

uv run python server.py --http

Custom network configuration via environment injection

HOST=127.0.0.1 PORT=9001 uv run python server.py --http

Setting persistent environment variables

export HOST=0.0.0.0 export PORT=8080 uv run python server.py --sse

Integration with FastMCP CLI

bash

Execute via the FastMCP wrapper

fastmcp run server.py

Register this service for use with Claude Desktop

fastmcp install server.py -n "Metabase Data Bridge"

Cursor IDE Integration

STDIO Transport Setup (Default)

bash uv run python scripts/install-cursor.py

SSE Transport Setup

bash

Install for default SSE port (8000)

uv run python scripts/install-cursor.py --sse

Install specifying a custom port

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

Alternative SSE installer 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: Ensure the server is active on the specified port before Cursor attempts connection: bash uv run python server.py --sse 8000

Claude Desktop Connectivity

After dependency resolution (uv sync), locate the interpreter path (e.g., ./.venv/bin/python). Update your Claude configuration file (~/Library/Application\ Support/Claude/claude_desktop_config.json) as follows:

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

🛠️ Exposed Toolset

Data Source Utilities

Function	Purpose
list_databases	Obtain a registry of all connected Metabase data repositories
list_tables	Retrieve comprehensive table listings and metadata for a given source
get_table_fields	Fetch detailed column definitions for a specified table

Data Retrieval Operations

Function	Purpose
execute_query	Process arbitrary SQL statements, accepting parameters
execute_card	Invoke and return results from a predefined Metabase Question/Card

Artifact Creation

Function	Purpose
list_cards	Get a directory of existing saved questions/cards
create_card	Programmatically define and save a new analytical card using SQL

Organizational Grouping

Function	Purpose
list_collections	Browse available organizational groupings
create_collection	Establish a new grouping structure

Transport Protocols

This service is versatile and supports three communication paradigms:

• STDIO (Default): Optimized for tight integration with local desktop applications (Cursor, Claude Desktop).
• SSE: Server-Sent Events, suitable for continuous updates in web contexts.
• HTTP: Standard REST-like interaction for broader API consumption.

Launch commands summary: bash uv run python server.py # STDIO uv run python server.py --sse # SSE on 0.0.0.0:8000 uv run python server.py --http # HTTP on 0.0.0.0:8000 HOST=127.0.0.1 PORT=8888 uv run python server.py --sse # Custom port/host

🧪 Development Lifecycle

Preparing the Development Environment

bash

Install core and dev dependencies

uv sync --group dev

Alternative using pip

pip install -r requirements-dev.txt

Code Quality Checks

bash

Comprehensive linting pass

uv run ruff check .

Code style correction

uv run ruff format .

Static type verification

uv run mypy server.py

Execute all unit and integration tests

uv run pytest -v

Run tests with code coverage report generation

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

System Validation

bash

Run the built-in setup checker utility

uv run python scripts/validate.py

📚 Operational Blueprints

Query Execution Samples

python

Catalog all available data repositories

repos = await list_databases()

Fire a data retrieval request

fetch_data = await execute_query( database_id=1, query="SELECT name, email FROM customer_roster WHERE created_at > '2023-01-01' LIMIT 10" )

Define and execute a new report artifact

new_report = await create_card( name="Monthly Revenue Summary", database_id=3, query="SELECT SUM(amount) FROM orders WHERE month = current_month()", collection_id=5 )

Example File Directory

• examples/quick-start.py - Initial setup tutorial
• examples/examples.py - Repository of standard interaction patterns
• examples/sse-example.py - Demonstration of SSE transport handling

📁 Repository Map

metabase-mcp/ ├── server.py # Primary service executable ├── pyproject.toml # Dependency and project manifest ├── .env.example # Template for configuration variables ├── scripts/ │ ├── install-cursor.py # Script for Cursor IDE integration │ ├── install-cursor-sse.py # Dedicated SSE installer for Cursor │ └── validate.py # Utility for verifying deployment integrity ├── examples/ # Code usage demonstrations ├── tests/ # Automated test suite └── docs/ # Supplementary documentation assets

🤝 Contribution Guidelines

We welcome external submissions! Please review the contribution process and submit a Pull Request.

📄 Licensing

This project is distributed under the MIT License. Refer to the LICENSE file for full terms.

🔗 External References

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

== Business Tool Context Summary == Business operation utilities encompass the array of applications, methodologies, control systems, and computational solutions employed by enterprises to maintain market relevance, adapt to shifting commercial environments, and enhance overall operational efficacy. These tools span functional silos within an organization, addressing aspects like strategic planning, workflow management, data recording, personnel administration, and executive decision support.

The rapid technological evolution of the past decade has dramatically altered the landscape of these utilities. The constant pressure for cost reduction, sales augmentation, deep customer insight acquisition, and precision product delivery necessitates a strategic approach. Managers must prioritize careful selection and subsequent customization of these tools to align with organizational specifics, rather than passively adopting the newest technology.

Dominant Utility Categories (Based on 2013 Global Survey)

Key areas prioritized by global businesses include:

1. Strategic Roadmap Development
2. Client Relationship Management (CRM)
3. Workforce Sentiment Assessment
4. Performance Comparison (Benchmarking)
5. Performance Measurement Frameworks (e.g., Balanced Scorecard)
6. Core Competency Identification
7. External Resource Management (Outsourcing)
8. Organizational Transition Management
9. Logistics and Vendor Management (SCM)
10. Foundational Statements (Mission/Vision)
11. Consumer Group Definition (Market Segmentation)
12. Quality Assurance Systems (TQM)

Evolution of Business Software

Business software—computer programs designed to streamline operations—has evolved from rudimentary Management Information Systems (MIS) to complex Enterprise Resource Planning (ERP) suites, incorporating Customer Relationship Management (CRM) capabilities, and currently migrating towards comprehensive cloud-based management platforms. Value addition beyond IT expenditure hinges on two critical success factors: the proficiency of the deployment and the judicious selection and tailoring of the software utilized.

Focus on Small and Medium Enterprises (SMEs)

Utilities tailored for SMEs are vital, providing accessible mechanisms to achieve efficiency improvements despite resource constraints.