Metabase

GitHub
Integrates with
Metabase

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:

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

  2. Build and run the Docker container:

    docker-compose up -d

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

Manual Installation

  1. Clone this repository:

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

  2. Install dependencies:

    pip install -r requirements.txt

  3. Run the configuration interface:

    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:

## 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:

## 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.