Metabase MCP Server: Setup, Tools & Real Limits
Metabase now ships an official MCP endpoint, but its permission model, write tools, and result ceilings deserve more attention than the quick-start implies.
Metabase MCP is the official bridge between an MCP-compatible AI client and a Metabase instance. Once connected, an agent can find tables and metrics, construct and run governed queries, inspect saved analytics, render simple charts, and create or update selected Metabase content—without receiving a direct warehouse login. It is useful, but not a blank cheque for autonomous BI.
Table of contents
- What Metabase MCP actually is
- What exists today
- How to set up Metabase MCP
- Tools you get
- Permissions and blast radius
- Real limits
- When not to use it
What Metabase MCP actually is
Metabase MCP is a remote MCP server built into Metabase, not a separate database connector. It exposes a controlled set of analytics operations at /api/metabase-mcp, while the model and conversation remain in whichever AI client you choose.
In practice, a user can ask an agent to find a revenue metric, inspect its fields, build a grouped query, execute it, and explain the returned rows. The agent can also retrieve Metabase entities such as dashboards, questions, models, and collections. In clients that support MCP Apps-style inline output, it can render bar, line, or table charts and drill into them. The official Metabase MCP documentation makes an important architectural point: the client supplies the AI; Metabase supplies tools and permission-scoped data.
That distinction matters. Results may be forwarded to the client’s model provider, so its retention settings belong inside your data boundary. The MCP Directory capabilities guide explains how tools, resources, and transport differ.
What exists today
The first-party server is the option we would deploy. Metabase introduced it in version 60, made it available across plans, and continues to document it as a built-in endpoint; upgrading is preferable to inserting an extra community proxy between an agent and production analytics.
Community projects such as 1luvc0d3/metabase-mcp and hyeongjun-dev/metabase-mcp-server predate or sit alongside the official implementation. They may cover older instances or more REST endpoints, but their authentication and guardrails are project-specific.
The Metabase 60 release announcement confirms the official server. Its trust model is simpler: vendor code, OAuth tied to a Metabase user, and no third-party proxy holding a key. Use a community server only for a verified missing requirement, then pin and review it. Find more first-party integrations in the MCP Directory official collection.
How to set up Metabase MCP
Setup is an admin enablement step followed by a user OAuth flow. You do not need to install an npm package or paste an API key into the official MCP connection.
Prerequisites
Use Metabase 60 or newer and a client supporting remote HTTP plus OAuth. The client must reach the instance, and the user needs appropriate data and collection permissions.
- In Metabase, open Admin > AI > MCP.
- Enable AI features, then enable the MCP server. A model provider is not required for MCP requests.
- Copy the server URL shown in settings:
https://your-metabase.example.com/api/metabase-mcp. - Add that remote URL to the client. For Claude Code, Metabase documents:
claude mcp add --transport http metabase https://your-metabase.example.com/api/metabase-mcp. - Start the client, select the server, choose Authenticate, and approve the Metabase consent page.
- Review tools in the client before the first real query.
Metabase embeds the OAuth server; the client registers, redirects the user, and receives permission-scoped access. There are no MCP scopes to hand-author. The underlying Agent API also accepts API keys, sessions, or JWT for custom apps, but those are not substitutes for the official MCP browser flow.
What commonly breaks
Most failures involve URL reachability. A reverse proxy must pass OAuth discovery and callbacks, and the public Site URL must be reachable by the client.
For local or container testing, the Site URL—and, when needed, MB_SITE_URL—must match the client URL or authentication may never open. Some desktop clients reject localhost. Use the exact endpoint; the MCP Directory config generator can translate a verified URL into a supported client format.
Tools you get
The official server exposes documented tools for discovery, querying, visualization, and selected content changes. A client may group them or request approval individually.
| Tool | What it does | Risk |
|---|---|---|
search | Finds tables and metrics by keyword or natural language | Read |
read_resource | Reads supported Metabase entities through metabase:// URIs | Read |
construct_query | Builds a query and returns an opaque handle | Read |
execute_query | Runs a constructed query with metadata and timing | Read |
query | Runs or continues a paginated query | Read |
visualize_query | Renders supported inline charts | Read |
render_drill_through | Renders a drill-through from an inline chart | Read |
create_collection | Creates a collection, optionally under a parent | Write |
create_dashboard | Creates a dashboard, optionally with saved questions | Write |
create_question | Saves a query as a named question | Write |
update_dashboard | Changes dashboard metadata or archives it | Write |
update_question | Changes or moves a saved question | Write |
execute_sql | Sends raw SQL to a permitted database | High |
The source of truth is Metabase’s available-tools list. This is not full administrative REST access: no documented tool creates users, changes permissions, adds databases, configures alerts, or builds transforms. That narrower surface is useful containment.
Permissions and blast radius
Use the connecting person’s least-privileged account and disable raw SQL unless it is genuinely necessary. Client-side tool approval is useful friction, but Metabase permissions and database credentials are the real security boundary.
OAuth carries the user’s Metabase permissions. A curator can let an agent move, archive, or overwrite shared content, disrupting links, subscriptions, and reporting. Audit membership: Metabase grants the most permissive access across all groups, including All Users, as its permissions documentation explains.
execute_sql requires native-query permission and can be disabled instance-wide with mcp-execute-sql-enabled. Unsupported writes may still work when database credentials permit them. Metabase recommends minimum read privileges and separate writable connections in its database privilege guide. Our default: read-only warehouse credentials, no raw SQL for ordinary users, and a sandbox collection.
Real limits
Metabase MCP is built for bounded analysis, not bulk extraction or unrestricted administration. Its hardest visible ceiling is query pagination: up to 200 rows per page and 2,000 rows total.
That cap does not solve context pressure. Two thousand wide rows can consume context, raise model cost, and bury the pattern. Request aggregations, date ranges, and necessary dimensions. The Agent API pagination documentation confirms 200 rows per page; MCP docs add the 2,000-row total.
Other boundaries are easy to miss:
read_resourceaccepts up to five entities or lists per call, and list resources return up to 25 items each.- Inline output supports bar, line, and table charts, not Metabase’s entire visualization catalog.
- The server cannot currently generate code or build transforms; Metabase explicitly contrasts those gaps with Metabot.
- Speed and concurrency depend on Metabase, its cache, and the warehouse. No universal MCP requests-per-minute quota is documented.
- A successful tool call is not proof of a correct business answer. Poor metric definitions, ambiguous joins, stale metadata, and an underspecified prompt still produce plausible mistakes.
Accept these limits for governed exploration, but move repeatable or high-volume work into tested code. Explore the best MCP servers only when cross-system context justifies another connection.
When not to use it
Do not use Metabase MCP when the task is repeatable, high-volume, or better completed inside Metabase. Choose the narrowest interface that produces an auditable result.
Use Metabot when users work inside Metabase and admins need AI controls, token limits, auditing, code generation, or transforms. Metabase calls MCP best for ad-hoc and cross-tool questions in its AI overview. The trade-off is portability versus centralized governance.
Use an Agent API or REST script for deterministic or scheduled jobs with retries and monitoring. Use warehouse-native jobs for bulk exports, transforms, and writes. Reserve Metabase MCP for supervised exploration, cross-system investigation, and draft analytics—not pipelines or unattended production changes.