This Metabase MCP Server exposes a Model Context Protocol interface that lets AI assistants and MCP clients query and control a Metabase instance. It supports database discovery, table and field inspection, native SQL execution, and management of cards (Metabase questions) and collections. Through MCP, you can perform natural language to SQL translations, run parameterized queries, and automate analytics workflows against your Metabase data. Typical use cases include asking an AI to list databases, fetch table schemas, run a complex query, or create and run cards based on user input. The server supports multiple transport modes (STDIO for IDEs like Cursor, SSE for web apps, and HTTP for API access) to fit different integration scenarios.

To use it, run the MCP server with a compatible transport (for example via uvx): uvx metabase-mcp. Once running, connect your MCP client (Claude Desktop, Cursor, or your own app) and point it at the server. Provide authentication via METABASE_URL and METABASE_API_KEY (or alternative email/password credentials via environment variables) and invoke the available tools such as list_databases, list_tables, get_table_fields, execute_query, execute_card, list_cards, create_card, list_collections, and create_collection. The server also supports environment-based configuration and can be started with custom HOST and PORT settings for SSE or HTTP transports.

If you’re integrating with Claude Desktop or Cursor, you can configure the client to connect to the running MCP server by supplying the server name metabase-mcp and the appropriate command and environment variables, ensuring secure access to your Metabase instance.

Prerequisites:

• Python 3.12+ (for Metabase MCP server runtime) or a compatible MCP runtime via uvx
• Metabase instance accessible via API (URL and API key or email/password credentials)
• Network access to the Metabase instance from the MCP server

Option A: Quick start with uvx (no local install required)

1. Ensure uvx is installed: pipx install uvx (or follow your platform’s uvx installation method)
2. Run the MCP server (env vars optional, use your own values): METABASE_URL=https://your-metabase-instance.com METABASE_API_KEY=your-api-key uvx metabase-mcp

Option B: Install from PyPI and run

1. Install the package (global install): uv tool install metabase-mcp

   or if you prefer pip directly (when using uv run):

   pip install metabase-mcp
2. Run the server (default transport will depend on your setup): metabase-mcp

Option C: Development / from source

1. Clone the repository: git clone https://github.com/cheukyin175/metabase-mcp.git cd metabase-mcp
2. Install dependencies: uv sync

   or use Python’s regular tooling if you’re not running via uvx

3. Run the server (examples): uv run python server.py

Notes:

• If you use uvx for run-time, you can rely on the package name metabase-mcp as shown above.
• For development, you may run the server directly with Python as server.py (e.g., uv run python server.py) and adjust transports via command-line flags.

Environment variables:

• METABASE_URL: Base URL for your Metabase instance
• METABASE_API_KEY: API key for authentication (preferred) OR METABASE_USER_EMAIL and METABASE_PASSWORD for legacy auth
• HOST/PORT: Optional overrides for SSE/HTTP transports Troubleshooting tips:
• Ensure Metabase is reachable from the MCP server network and that the API key has appropriate permissions.
• If you encounter ToolError responses, check the server logs for error details and verify SQL syntax or card creation parameters.
• For Claude Desktop integration, you can add an MCP config JSON with mcpServers.metabase-mcp pointing to uvx or uv, as shown in the README examples.
• Transport choice (STDIO, SSE, HTTP) impacts how you connect from clients; ensure the chosen port is open and not blocked by a firewall.
• When using environment-based authentication, keep credentials out of version control and consider using a .env file with proper access protections.