Content
# 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)
1. Clone this repository:
```bash
git clone https://github.com/yourusername/metabase-mcp.git
cd metabase-mcp
```
2. Build and run the Docker container:
```bash
docker-compose up -d
```
3. Access the configuration interface at http://localhost:5001
### Manual Installation
1. Clone this repository:
```bash
git clone https://github.com/yourusername/metabase-mcp.git
cd metabase-mcp
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
3. Run the configuration interface:
```bash
python -m src.server.web_interface
```
4. Access the configuration interface at http://localhost:5000
## Configuration
1. Open the web interface in your browser
2. Enter your Metabase URL (e.g., http://localhost:3000)
3. Enter your Metabase API key
4. Click "Save Configuration" and test the connection
### Obtaining a Metabase API Key
1. Log in to your Metabase instance as an administrator
2. Go to Settings > Admin settings > API Keys
3. Create a new API key with appropriate permissions
4. Copy the generated key for use in the MCP server
## Usage
### Running the MCP Server
After configuration, you can run the MCP server:
```bash
# 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:
1. **list_databases**: List all databases configured in Metabase
2. **get_database_metadata**: Get detailed metadata for a specific database
3. **db_overview**: Get a high-level overview of all tables in a database
4. **table_detail**: Get detailed information about a specific table
5. **visualize_database_relationships**: Generate a visual representation of database relationships
6. **run_database_query**: Execute a SQL query against a database
7. **list_actions**: List all actions configured in Metabase
8. **get_action_details**: Get detailed information about a specific action
9. **execute_action**: Execute a Metabase action with parameters
### Testing Tools via Web Interface
The web interface provides a testing area for each tool:
1. **List Databases**: View all databases configured in Metabase
2. **Get Database Metadata**: View detailed schema information for a database
3. **DB Overview**: View a concise list of all tables in a database
4. **Table Detail**: View detailed information about a specific table
5. **Visualize Database Relationships**: Generate a visual representation of table relationships
6. **Run Query**: Execute SQL queries against databases
7. **List Actions**: View all actions configured in Metabase
8. **Get Action Details**: View detailed information about a specific action
9. **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:
1. Implement the tool function in `src/tools/`
2. Register the tool in `src/server/mcp_server.py`
3. Add a testing interface in `templates/config.html` (optional)
4. 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:
```bash
# 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.
