metabase

This MCP server provides a bridge to the Metabase API, exposing capabilities such as listing cards and databases, executing queries on cards, running arbitrary queries, creating new cards, creating bookmarks, and listing collections. It is designed to be run under UV as a Python-based server that speaks the MCP protocol, enabling your AI assistant or client to interact with Metabase programmatically. Once running, you can leverage the available MCP endpoints to fetch metadata, run Metabase queries, and perform common content management operations within Metabase.

To use the server, ensure your MCP client is configured to connect to the Metabase MCP server (the configuration example in the repository shows how to wire the UV-based runner, including required environment variables). The tools you can access via MCP typically include commands for listing resources (cards, databases, collections), executing queries on cards, running arbitrary queries, and creating new cards or bookmarks. Provide the necessary parameters through the MCP interface (e.g., card IDs, query payloads, database identifiers) and the server will translate those into Metabase API calls and return results back to your client.

Prerequisites

• Python 3.12+
• uv (the Python UV library) installed
• Access to a Metabase instance with an API key

Step-by-step installation

1. Clone the repository

git clone https://github.com/cuenca-mx/metabase-mcp-server.git
cd metabase-mcp-server

2. Install dependencies and set up development environment

# If a Makefile is provided, you can use make install (as described in the repo)
make install

3. Configure the MCP server in your client by adding the following configuration (adjust paths and keys as needed)

{
  "mcpServers": {
    "metabase": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/metabase_mcp_server",
        "run",
        "app.py"
      ],
      "env": {
        "METABASE_URL": "https://metabase.domain.com/",
        "METABASE_API_KEY": "your-secret-api-key"
      }
    }
  }
}

4. Run tests (optional)

uv run pytest

5. Start development workflow (if needed)

make dev

6. Verify the server is reachable via MCP tools and that Metabase integration behaves as expected.

Environment variables: METABASE_URL and METABASE_API_KEY must be set with your Metabase instance URL and a valid API key. If you change the Metabase URL or credentials, update the env block accordingly. Common issues include improper relative paths for the app.py script or missing dependencies in the Python environment. Ensure Python 3.12+ is installed and accessible to uv. When debugging, use the MCP Inspector or the provided dev workflow to validate MCP calls and responses. If you encounter authentication errors, re-check API key permissions in Metabase and verify network access from the host running the MCP server.