Metabase MCP Server
A Model Control Protocol (MCP) server that enables AI assistants to interact with Metabase databases and actions.
![Metabase MCP Server]
Overview
The Metabase MCP Server provides a bridge between AI assistants and Metabase, allowing AI models to:
- List and explore databases configured in Metabase
- Retrieve detailed metadata about database schemas, tables, and fields
- Visualize relationships between tables in a database
- List and execute Metabase actions
- Perform operations on Metabase data through a secure API
This server implements the [Model Control Protocol (MCP)] specification, making it compatible with AI assistants that support MCP tools.
Features
- Database Exploration: List all databases and explore their schemas
- Metadata Retrieval: Get detailed information about tables, fields, and relationships
- Relationship Visualization: Generate visual representations of database relationships
- Action Management: List, view details, and execute Metabase actions
- Secure API Key Handling: Store API keys encrypted and prevent exposure
- Web Interface: Test and debug functionality through a user-friendly web interface
- Docker Support: Easy deployment with Docker and Docker Compose
Prerequisites
- Metabase instance (v0.46.0 or higher recommended)
- Metabase API key with appropriate permissions
- Docker (for containerized deployment)
- Python 3.10+ (for local development)
Installation
Using Docker (Recommended)
-
Clone this repository:
git clone https://github.com/yourusername/metabase-mcp.git cd metabase-mcp -
Build and run the Docker container:
docker-compose up -d -
Access the configuration interface at http://localhost:5001
Manual Installation
-
Clone this repository:
git clone https://github.com/yourusername/metabase-mcp.git cd metabase-mcp -
Install dependencies:
pip install -r requirements.txt -
Run the configuration interface:
python -m src.server.web_interface -
Access the configuration interface at http://localhost:5000
Configuration
- Open the web interface in your browser
- Enter your Metabase URL (e.g., http://localhost:3000)
- Enter your Metabase API key
- Click "Save Configuration" and test the connection
Obtaining a Metabase API Key
- Log in to your Metabase instance as an administrator
- Go to Settings > Admin settings > API Keys
- Create a new API key with appropriate permissions
- Copy the generated key for use in the MCP server
Usage
Running the MCP Server
After configuration, you can run the MCP server:
# Using Docker
docker run -p 5001:5000 metabase-mcp
# Manually
python -m src.server.mcp_server
Available Tools
The MCP server provides the following tools to AI assistants:
- list_databases: List all databases configured in Metabase
- get_database_metadata: Get detailed metadata for a specific database
- db_overview: Get a high-level overview of all tables in a database
- table_detail: Get detailed information about a specific table
- visualize_database_relationships: Generate a visual representation of database relationships
- run_database_query: Execute a SQL query against a database
- list_actions: List all actions configured in Metabase
- get_action_details: Get detailed information about a specific action
- execute_action: Execute a Metabase action with parameters
Testing Tools via Web Interface
The web interface provides a testing area for each tool:
- List Databases: View all databases configured in Metabase
- Get Database Metadata: View detailed schema information for a database
- DB Overview: View a concise list of all tables in a database
- Table Detail: View detailed information about a specific table
- Visualize Database Relationships: Generate a visual representation of table relationships
- Run Query: Execute SQL queries against databases
- List Actions: View all actions configured in Metabase
- Get Action Details: View detailed information about a specific action
- Execute Action: Test executing an action with parameters
Security Considerations
- API keys are stored encrypted at rest
- The web interface never displays API keys in plain text
- All API requests use HTTPS when configured with a secure Metabase URL
- The server should be deployed behind a secure proxy in production environments
Development
Project Structure
metabase-mcp/
├── src/
│ ├── api/ # Metabase API client
│ ├── config/ # Configuration management
│ ├── server/ # MCP and web servers
│ └── tools/ # Tool implementations
├── templates/ # Web interface templates
├── docker-compose.yml # Docker Compose configuration
├── Dockerfile # Docker build configuration
├── requirements.txt # Python dependencies
└── README.md # Documentation
Adding New Tools
To add a new tool:
- Implement the tool function in
src/tools/ - Register the tool in
src/server/mcp_server.py - Add a testing interface in
templates/config.html(optional) - Add a route in
src/server/web_interface.py(if adding a testing interface)
Troubleshooting
Common Issues
- Connection Failed: Ensure your Metabase URL is correct and accessible
- Authentication Error: Verify your API key has the necessary permissions
- Docker Network Issues: When using Docker, ensure proper network configuration
Logs
Check the logs for detailed error information:
# Docker logs
docker logs metabase-mcp
# Manual execution logs
# Logs are printed to the console
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.