# Setup Metabase MCP

> Read these instructions before using Metabase MCP tools. Setup is needed to connect to Metabase instances via the built-in MCP server.

- Skill: `metabase/setup-metabase-mcp` (Agent Skill)
- Install (CLI): `npx skillmds@latest add metabase/setup-metabase-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/metabase/setup-metabase-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: metabase (https://skillmd.com/u/metabase)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/metabase/setup-metabase-mcp

---


Read these mandatory configuration steps for using the Metabase MCP server before querying data, dashboards, questions, and related resources.

**Location**: The MCP configuration file is `../../mcp.json` relative to this SKILL.md file — two directories up, in the same folder that contains the `skills/` directory. Always resolve this path relative to this SKILL.md file, never relative to the user's open project.

**Important Requirement**: The `url` field in that file may contain `{METABASE_INSTANCE_PLACEHOLDER}` as the base URL (e.g. `"{METABASE_INSTANCE_PLACEHOLDER}/api/mcp"`). If so, it must be replaced with the user's actual Metabase instance URL before the MCP can work.

## Valid Instance URL Formats

- Local development: `http://localhost:3000`
- Metabase Cloud: `https://yourcompany.metabaseapp.com`
- Self-hosted: `https://metabase.yourcompany.com`

## Required Actions

1. Read `../../mcp.json` relative to this SKILL.md file.

2. Check whether the `url` field contains `{METABASE_INSTANCE_PLACEHOLDER}`.
   - **If it does NOT contain `{METABASE_INSTANCE_PLACEHOLDER}`**: the MCP is already configured. **Immediately proceed with using the Metabase MCP. Do not ask the user for a URL under any circumstances.**
   - **If it does contain `{METABASE_INSTANCE_PLACEHOLDER}`**: continue with the steps below.

3. **Stop all other exploration immediately** and ask the user for their Metabase instance URL. Do not search for tool schemas, read other files, or do anything else first.

   **Never mention `{METABASE_INSTANCE_PLACEHOLDER}` or any placeholder to the user**. Simply say the MCP needs their Metabase URL to connect.

   Ask the user: "Do you have a Metabase instance URL, or would you like to set up a local instance?"
   - **If they provide a URL**: Continue with step 4.
   - **If they don't have one and want to set up a local instance**: Invoke the `setup-metabase-instance` skill. Once the local instance is running, return here and use `http://localhost:3000` (or whatever port was chosen) as the instance URL.

4. Once the user provides the URL, run **exactly this command and no other** — do not try alternative endpoints or approaches:

   ```bash
   curl -s <INSTANCE_URL>/api/session/properties | grep -o '"tag":"[^"]*"'
   ```

   This returns something like `"tag":"v1.60.0"`. Extract the major version number (e.g. `60` from `v1.60.0`). If it is below 60, tell the user they need to upgrade and stop — do not update `mcp.json`.

5. Replace the placeholder in `../../mcp.json` relative to this SKILL.md with the user's instance URL. Strip any trailing slash before saving — do not mention this to the user.

6. Only after updating the file, tell the user they need to reload the window.

   Use the user's current OS to show the right shortcut: open the Command Palette (⌘⇧P on Mac or Ctrl+Shift+P on Windows/Linux) and run **"Reload Window"**. Ask them to confirm once reloaded before continuing.

7. Once the user confirms the window has been reloaded, call the `mcp_auth` tool for the Metabase MCP server to authenticate. This will prompt the user to log in to their Metabase instance.

8. Proceed with using the Metabase MCP

**Important**: Do not attempt to access MCP tools or schemas until the authentication is complete. Never reveal `{METABASE_INSTANCE_PLACEHOLDER}` or any internal placeholder names to the user.