metabase

Metabase MCP Server acts as a bridge between a Metabase instance and AI assistants via the MCP protocol. It lets you interact with Metabase assets—such as dashboards, charts, and questions—using natural language through MCP clients. With this server running, you can ask questions about dashboards, request the generation of new dashboards or charts by describing what you want, and manage access or connections through simple prompts. The server translates natural language requests into Metabase operations and returns results or generated content back to the client. Tools available include querying dashboards, creating visualizations from descriptions, and guiding access/configuration changes within Metabase, all through conversational prompts in supported MCP clients like Claude Desktop, Cursor, Windsurf, or similar integrations.

Prerequisites

• Metabase instance up and running (Metabase URL and access credentials)
• Python installed (preferred via uv as described in the project setup)
• Access to install and run the MCP server from the repository

Installation steps

1. Set up Metabase locally or on a server so the MCP server can reach it. Ensure METABASE_URL points to this instance and an API key is generated for programmatic access.

2. Install uv (Python package manager) if not already installed. Follow the instructions in the project guide for your OS:

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

3. Clone the repository (or download the ZIP) and navigate to the project folder:

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

4. Install dependencies with uv:

uv sync

5. Configure credentials (one of the options):

• Option A: Create a .env file in the project root with the following:

METABASE_URL=http://localhost:3000
METABASE_API_KEY=mb_xxx_your_key
PORT=3200
HOST=localhost
TRANSPORT=streamable-http
LOG_LEVEL=DEBUG

• Option B: Use command-line arguments to run the server with credentials:

uv run src/metabase_mcp_server.py --metabase-url http://localhost:3000 --metabase-api-key "YOUR_API_KEY" --port 3200 --host localhost --transport streamable-http --log-level DEBUG

• Option C: Configure credentials in the MCP client config (see the README examples) using an env block in your mcpServers entry.

6. Start the MCP server (via the chosen method). Verify it is reachable by your MCP client (stdio transport or streamable-http as configured).

7. Connect an MCP client to the server using the provided mcpServers configuration (stdio or streamable-http). Refer to the client’s documentation for exact steps.

Tips and notes:

• Ensure METABASE_URL and METABASE_API_KEY are valid and that the Metabase instance allows API access.
• If using streamable-http, ensure the server is accessible at the configured URL (e.g., http://localhost:3200/mcp/). Firewalls and network rules may affect access.
• The logs (LOG_LEVEL) can help diagnose issues during development; switch to DEBUG if you’re troubleshooting.
• When migrating between environments (dev, staging, prod), update the METABASE_URL, API keys, and transport settings accordingly.
• If you encounter transport issues, verify that the MCP client configuration matches the server’s transport type (stdio vs streamable-http).
• This MCP server supports interacting with Metabase assets via natural language prompts, enabling rapid BI-driven QA, dashboard generation, and configuration guidance through supported MCP clients.