Metabase Model Control Protocol (MCP) Conduit

A specialized MCP server designed to empower intelligent agents with robust connectivity to Metabase data stores and associated functions.

![Metabase MCP Server Schematic]

Synopsis

The Metabase MCP Conduit establishes a reliable communication layer between sophisticated AI entities and the Metabase ecosystem. This allows AI models to:

• Enumerate and inspect the Metabase collection of accessible data sources
• Fetch exhaustive metadata pertaining to data schemas, constituent tables, and individual field attributes
• Generate graphical representations illustrating inter-table dependencies within a dataset
• Catalog and trigger defined Metabase operational routines
• Effectuate data manipulations within Metabase through a cryptographically secured API endpoint

This application adheres strictly to the [Model Control Protocol (MCP)] specification, ensuring broad compatibility with MCP-enabled AI tooling.

Key Capabilities

• Data Source Traversal: Inventory all databases and probe their internal compositions
• Granular Attribute Fetching: Obtain comprehensive details on tables, fields, and relational connections
• Dependency Mapping: Produce visual blueprints of database interconnections
• Routine Lifecycle Management: List, examine specifications for, and invoke Metabase-defined operations
• Credential Sanctuary: Store sensitive access tokens using strong encryption methods, preventing unauthorized disclosure
• Utility Frontend: Offer a browser-based environment for functional validation and debugging
• Containerization Ease: Simplified deployment utilizing Docker and Docker Compose utilities

System Prerequisites

• An operational Metabase installation (version 0.46.0 or newer is suggested)
• A Metabase generated API credential possessing requisite access rights
• Docker Engine (necessary for container deployment scenarios)
• Python version 3.10 or later (for local software development)

Deployment Procedures

Containerized Approach (Recommended)

1. Clone the repository source code: bash git clone https://github.com/yourusername/metabase-mcp.git cd metabase-mcp

2. Initiate and construct the Docker container environment: bash docker-compose up -d

3. Access the configuration portal at http://localhost:5001

Standalone Installation

1. Clone the repository source code: bash git clone https://github.com/yourusername/metabase-mcp.git cd metabase-mcp

2. Resolve and install required software dependencies: bash pip install -r requirements.txt

3. Launch the setup interface executable: bash python -m src.server.web_interface

4. Access the configuration portal at http://localhost:5000

Configuration Steps

1. Navigate to the service interface within a web browser
2. Input the base URL for your Metabase deployment (e.g., http://localhost:3000)
3. Supply the requisite Metabase API access token
4. Activate the "Secure Configuration" prompt and execute a connectivity verification

Acquiring Metabase Authorization Tokens

1. Log into your Metabase console with administrative privileges
2. Navigate through Settings -> Administrator Controls -> API Key Management
3. Generate a fresh credential, ensuring it has the appropriate operational scope
4. Securely copy the resultant key for input into the MCP server

Operational Guide

Activating the MCP Service Core

Once configuration parameters are set, initiate the MCP communication hub:

bash

For Docker deployment

docker run -p 5001:5000 metabase-mcp

For manual execution

python -m src.server.mcp_server

Available Toolset Interfaces

The core server exposes the subsequent operational modules to connected AI agents:

1. list_databases: Retrieves a catalog of all Metabase-registered data repositories
2. get_database_metadata: Fetches comprehensive schema specifications for a chosen repository
3. db_overview: Provides a summarized inventory of tables within a specified data repository
4. table_detail: Obtains granular attribute data for an individual table entity
5. visualize_database_relationships: Renders a graphic illustration of data linkages
6. run_database_query: Executes arbitrary Structured Query Language commands against a data repository
7. list_actions: Enumerates all configurable routine triggers within Metabase
8. get_action_details: Fetches the parameter schema for a specific routine trigger
9. execute_action: Initiates the execution of a Metabase routine with supplied arguments

Tool Validation via Web Console

The provided web interface features dedicated testing panels for each exposed module:

1. Database Listing: Review the complete set of configured Metabase repositories
2. Schema Examination: Inspect detailed structural data for any repository
3. Repository Summary: View a succinct listing of all contained tables
4. Table Specification: Access in-depth metadata for a selected table
5. Interconnect Visualization: Generate graphical relation maps
6. Query Execution Sandbox: Run and validate SQL instructions
7. Routine Catalog View: See all accessible Metabase operational routines
8. Routine Parameter Check: View the required inputs for any routine
9. Routine Invocation Test: Stress-test action execution with specified parameters

Security Posture

• Access credentials are encrypted using industry-standard algorithms when persisted on disk
• The administrative web interface is engineered never to render plaintext API credentials
• All API communications default to HTTPS when integrated with a secure Metabase endpoint URL
• For production deployments, routing the server traffic through a trusted, secure reverse proxy is mandatory

Development Workflow

Source Code Organization

metabase-mcp/ ├── src/ # Core API client logic │ ├── api/ # Metabase communication handlers │ ├── config/ # Configuration persistence and retrieval module │ ├── server/ # MCP and Web server implementations │ └── tools/ # Individual tool function definitions ├── templates/ # Frontend HTML assets ├── docker-compose.yml # Multi-container orchestration file ├── Dockerfile # Image build specification ├── requirements.txt # Python package dependencies list └── README.md # Primary documentation file

Extending Functionality (Adding New Tools)

To integrate an additional utility:

1. Code the desired function within a new file in src/tools/
2. Register the new function within the primary tool registry file, src/server/mcp_server.py
3. Optionally, create a corresponding testing interface element in templates/config.html
4. If a testing panel is added, map its endpoint in src/server/web_interface.py

Troubleshooting Guide

Common Operational Failures

• Connectivity Halt: Confirm the Metabase base URL is accurate and network reachable
• Authorization Rejection: Re-validate the API token and confirm its assigned operational permissions
• Container Networking Glitches: When operating within Docker, inspect the internal network bridge settings

Log Analysis

Refer to the system output streams for detailed error narratives:

bash

Checking Docker container logs

docker logs metabase-mcp

Logs from direct execution

Output is streamed directly to the console session

Community Contributions

Submissions and enhancements are highly valued! Please utilize the Pull Request mechanism to propose changes.