Metabase MCP Server: Connect Claude to Your Data

The Metabase MCP server is a bridge that lets Claude, Cursor, VS Code, and other AI tools query your data with natural language. MCP stands for Model Context Protocol, a standard that connects large language models to external tools and data sources. Instead of manually running queries or navigating dashboards, your AI assistant can explore databases, generate reports, and answer data questions on its own.

This guide walks you through setup, security, and real-world use cases without the admin jargon.

What is Metabase MCP and Why Your Team Needs It?

Metabase MCP exposes your Metabase instance as a tool that AI assistants can use. When you enable it, Claude can ask questions like "What was our revenue last quarter by product?" and the AI queries Metabase directly, reads the results, and gives you the answer. No copy-pasting data. No waiting for a team member to run a report.

The Model Context Protocol is not Metabase-specific. It is an open standard that Anthropic created to standardize how AI assistants connect to external systems. Think of it as a universal adapter: MCP lets any MCP-compatible client (Claude, Cursor, custom tools) talk to any MCP-compatible server (Metabase, PostgreSQL connectors, file systems, APIs). Metabase added MCP support in v0.64, making it one of the few BI tools with native AI integration.

For your team, this means:

• Your product team can ask Claude about user metrics without SQL knowledge.
• Your finance team can ask about spending trends and get instant answers.
• Your engineers can diagnose performance issues by querying logs and metrics through Claude.
• You keep all data inside your Metabase instance, not copied into AI chat interfaces.

The catch: Metabase MCP does not auto-magically make your data secure. You still need to create read-only database users, restrict table access, and think about what an AI assistant should be allowed to see. If your Metabase instance touches sensitive customer data, PII, or financial records, permission management is not optional.

Official vs. Community MCP Servers: Which Should You Choose?

There are two main implementations: the official Metabase MCP server (built into v0.64+) and community alternatives like the TypeScript implementation from imlewc/metabase-server (151 GitHub stars).

The official Metabase MCP server is the simplest choice if you are running Metabase v0.64 or later. It lives inside Metabase itself. No separate installation, no dependency management. Metabase handles updates and security patches as part of regular releases. It exposes the same data and permission model your Metabase admin panel uses, so if a user can see a dashboard in Metabase, the AI assistant can query the underlying data.

Community implementations exist for older Metabase versions or if you want more control over MCP behavior. The imlewc/metabase-server project is a TypeScript server that wraps Metabase's REST API and exposes it via MCP. It runs separately from Metabase, so you can customize it or run it in a different environment. The tradeoff: you are responsible for keeping it updated, managing dependencies, and ensuring it stays in sync with your Metabase schema changes.

Our recommendation: start with the official server if you are on v0.64+. It requires zero setup beyond enabling a toggle. If you are stuck on an older Metabase version or need custom behavior, evaluate community options, but know you are taking on maintenance overhead.

Here is a quick comparison:

Feature	Official Metabase MCP	Community (imlewc/metabase-server)
Metabase version required	v0.64+	Typically v0.45+
Installation	Built-in, enable in admin UI	Separate Node.js app
Maintenance	Handled by Metabase team	Your responsibility
Customization	Limited to Metabase UI settings	Full source code control
Support	Metabase community + docs	Community GitHub

Prerequisites: Versions, Permissions & User Setup

Before you enable MCP, make sure you have the right foundation in place.

Metabase version: You need Metabase v0.64 or later. If you are running an older version, either upgrade or use a community implementation. You can check your version in the Metabase admin panel under Settings > About.

A read-only database user: Do not use your admin database credentials for the AI assistant. Create a dedicated read-only user that can SELECT from specific tables or databases, but cannot INSERT, UPDATE, DELETE, or DROP. The exact steps depend on your database type (PostgreSQL, MySQL, Snowflake, etc.), but the principle is the same: least privilege. Give the AI assistant access only to data it actually needs to answer questions.

Metabase API key: The MCP server needs an API key to authenticate with Metabase. You generate this in the admin panel under Settings > Admin Settings > API Key. This key is sensitive. Treat it like a password. If the AI assistant runs in a shared environment (like a Cursor window on a team member's computer), the key sits in their config. Rotate it if someone leaves the team or loses a laptop.

Planned data scope: Before you give Claude access to your Metabase, decide what data it should see. Should it access production customer data? Only aggregated metrics? Specific departments? Write this down. It will inform which database tables you expose to the read-only user, and which Metabase permissions you configure later.

Optional: A read-only Metabase user account: You can assign the API key to a regular Metabase user account with read-only permissions. This is cleaner for auditing and makes it easier to revoke AI assistant access without regenerating the API key. Create a user called "Claude Bot" or "AI Assistant" with permission to view only the collections and databases you planned above.

Step 1: Enable MCP on Your Metabase Instance

Assuming you are running Metabase v0.64 or later and have admin access:

1. Log in to Metabase as an admin.
2. Click the Settings gear icon in the top right.
3. Go to Admin Settings (or just Settings on some versions).
4. Look for AI or Model Context Protocol in the left sidebar. Click it.
5. Toggle Enable Metabase MCP Server to ON.
6. Metabase will display your MCP server URL. If you're running locally, it will include localhost. If you're hosting Metabase on a domain, it will use your domain name. You'll need this URL in the next step--copy and save it.
7. Save.

That is it. Metabase is now running an MCP server. The server is listening at the URL shown, ready to accept MCP connections.

If you don't see an AI or MCP option in Settings, double-check your Metabase version. You need v0.64 or later. Older versions do not have MCP built-in.

Step 2: Connect Claude, Cursor, or VS Code to Your Metabase

Now you connect your AI tool to the MCP server. The steps differ depending on which tool you are using.

Connecting Claude (Claude.ai or Claude with Claude for Web):

Claude.ai does not currently support custom MCP servers in the free web interface. However, if you use Claude through the Claude API or a compatible client, you can configure MCP. Check Anthropic's documentation for your specific tool. The general pattern is to add an mcp_servers configuration with your Metabase URL and API credentials.

Connecting Cursor:

Cursor is an AI-powered code editor that supports MCP natively. Here is how to add your Metabase server:

1. Open Cursor.
2. Go to Settings (or Cursor Settings on Mac).
3. Find MCP Servers in the settings.
4. Click Add MCP Server or +.
5. Select Custom.
6. In the URL field, paste the Metabase MCP server URL you copied in Step 1.
7. In the API Key field, paste your Metabase API key.
8. Click Save or Connect.

Cursor will now list Metabase in its tools. When you ask Cursor a question about your data, it can use Metabase as a source of truth.

Connecting VS Code (with a compatible MCP client extension):

VS Code does not have built-in MCP support, but you can install extensions that add it. Popular options include extensions that support Anthropic's MCP protocol. Once installed:

1. Open the extension settings.
2. Add your Metabase URL and API key to the MCP server configuration.
3. Restart VS Code.

The exact steps depend on which extension you use, so consult the extension documentation.

Generic MCP Client:

If you are building your own tool or using a platform that supports MCP, the setup is:

• MCP Server Type: HTTP or WebSocket (depends on your Metabase hosting)
• Server URL: The URL from Step 1
• Authentication: Include your Metabase API key in the Authorization header or as a query parameter (check Metabase docs for the exact format)

Once connected, test the connection by asking a simple question: "What tables are in my Metabase?" The AI tool should query Metabase and list the available tables. If you get an error, check the next section on troubleshooting.

Step 3: Set Read-Only Permissions & Restrict Database Access

This is the security step that many teams skip, and it is a mistake. If you connect Claude to your production Metabase without restrictions, it can access any data any authenticated Metabase user can see. That includes PII, payment information, health records, and financial data. Here is how to lock it down.

Step 1: Create a read-only database user.

On your database (PostgreSQL, MySQL, Snowflake, etc.), create a new user that can only SELECT from specific tables:

For PostgreSQL:

CREATE ROLE metabase_ai WITH LOGIN PASSWORD 'strong_random_password';
GRANT USAGE ON SCHEMA public TO metabase_ai;
GRANT SELECT ON public.users TO metabase_ai;
GRANT SELECT ON public.orders TO metabase_ai;

For MySQL:

CREATE USER 'metabase_ai'@'localhost' IDENTIFIED BY 'strong_random_password';
GRANT SELECT ON your_database.users TO 'metabase_ai'@'localhost';
GRANT SELECT ON your_database.orders TO 'metabase_ai'@'localhost';
FLUSH PRIVILEGES;

Only grant SELECT on tables the AI assistant actually needs. If it does not need access to customers_payment_methods, do not grant it.

Step 2: Create a Metabase account for the AI assistant.

1. In Metabase, go to Settings > Users and Groups.
2. Click New User.
3. Name it "Claude Bot" or "AI Assistant".
4. Set the password to something long and random (you won't use it; the API key is the credential).
5. Click Create.

Step 3: Restrict this user's permissions.

1. Go to Settings > Permissions.
2. Find the "Claude Bot" user.
3. Set Native query to None (AI should not run raw SQL).
4. For each database, set the permission to Restricted and choose only the specific tables or databases the AI should see.
5. Save.

Step 4: Generate an API key for this user.

1. Go to Settings > Admin Settings > API Keys.
2. Click Create API Key.
3. Assign it to the "Claude Bot" user.
4. Copy the key and store it securely (in your Cursor config, environment variables, etc.).
5. Do NOT commit it to git or share it in Slack.

Now, when Claude connects to Metabase via MCP, it can only access the tables you explicitly allowed. If someone compromises the API key, the attacker can only read the restricted tables, not your entire database.

Avoiding prompt injection:

Prompt injection is a risk when AI assistants can execute queries. If a user asks Claude "What is the data for the email 'admin@example.com; DROP TABLE users; --'?", Claude might inadvertently execute a destructive SQL command. The MCP server itself guards against this by enforcing database permissions (the read-only user cannot DROP), but be aware of the risk. Keep Claude's access truly read-only.

What Your AI Assistant Can Now Do: Real Examples

Once set up, your AI assistant can answer data questions without you running reports. Here are concrete examples:

Example 1: Revenue trends

You ask Claude: "What was our revenue by month for 2026?"

Claude queries Metabase, retrieves the aggregated revenue data (assuming you have an orders table with order dates and amounts), and responds: "Your revenue grew from $50K in January to $120K in October, with the biggest jump in August."

Example 2: User cohorts

You ask Claude: "How many new users signed up in September?"

Claude queries the users table, filters for created_at in September, counts the rows, and tells you: "1,247 new users signed up in September."

Example 3: Debugging with data

You ask Claude: "We had a spike in cancelled subscriptions last week. What changed?"

Claude queries your subscriptions table, compares cancellation rates week-over-week, and might discover: "Cancellations spiked on October 20. Orders for the 'Pro Plan' had a 15% cancellation rate that day, compared to 2% the week before. This correlates with your Pro Plan price increase announced on October 19."

Example 4: Exploration during problem-solving

You are troubleshooting a bug with a Cursor window open. You tell Claude: "Our analytics query is timing out. Show me the largest tables in the database by row count."

Claude queries information_schema.tables (if permissions allow) and reports: "Your events table has 450M rows. The users table has 2.3M rows. The events table might be your bottleneck."

Example 5: Automating reporting

You ask Claude: "Generate a summary of this week's top-performing pages by traffic."

Claude queries your page_views table, groups by page, sorts by count, and gives you a ranked list with percentages, all without you logging into Metabase or writing SQL.

The key constraint: Claude can only query data that exists in Metabase dashboards, saved questions, and the underlying tables you exposed. It cannot create new tables, modify schema, or run unvetted SQL. This is by design.

Troubleshooting: Connection Issues & Permission Errors

Issue: "Connection refused" or "Cannot reach Metabase"

Possible causes:

• Metabase is not running. Make sure your Metabase instance is up and reachable from the client (Claude, Cursor, etc.).
• The URL is wrong. Double-check the MCP server URL from Step 1. It should include the full protocol (http:// or https://) and port if not standard.
• Firewall or network issues. If Metabase is behind a firewall or VPN, Cursor or your tool might not reach it. Verify network connectivity.
• CORS issues (if using Claude web interface). Metabase may require CORS configuration to allow requests from Claude's domain.

Issue: "Unauthorized" or "API key invalid"

Possible causes:

• API key is wrong. Regenerate it in Settings > API Keys and update your config.
• API key is expired or revoked. Metabase lets admins invalidate API keys. Check if yours is still active.
• API key is assigned to a user with no Metabase permissions. Make sure the user account the key is assigned to has at least read access to the databases you want the AI to see.

Issue: "Permission denied" or "Table not found"

Possible causes:

• The table is not in the databases you gave the user permission to access. Check Settings > Permissions.
• The table name is different than you think. Use Metabase's UI to verify the actual table name (sometimes it is different from the database schema name).
• The read-only database user does not have SELECT on that table. Check your database user grants with SHOW GRANTS or GRANT statements.

Issue: AI assistant returns vague answers like "I cannot query your database"

This usually means the AI tool is not successfully connecting to Metabase, or the MCP server is not returning results. Check:

• Is MCP enabled in Metabase admin settings?
• Can you reach the MCP server URL directly in a browser or with curl? It should return some response (even an error is better than timeout).
• Are there error logs in Metabase (Settings > Logs)? They might reveal what is failing.

Issue: Metabase says "MCP Server Error" or crashes when MCP is enabled

This is rare in v0.64+, but if it happens:

• Restart Metabase.
• Disable MCP, restart, then re-enable it.
• Check Metabase release notes for known MCP bugs in your version. You might need to upgrade.
• Ask the Metabase community on Discourse or GitHub.

Frequently Asked Questions

Is there an official Metabase MCP server?

Yes. Metabase v0.64 and later include an official MCP server built in. You enable it in Settings > AI. No separate installation needed. Older versions do not have it, and you would need a community implementation.

How do I connect Metabase to Claude?

You enable Metabase MCP, get the server URL and API key, then add them to your Claude client (Cursor, VS Code extension, or custom tool) under MCP server settings. Claude.ai (the free web version) does not currently support custom MCP servers directly, but Claude API and compatible clients do.

How do I use the Metabase MCP server in Cursor or VS Code?

In Cursor, go to Settings > MCP Servers > Add Custom, paste your Metabase URL and API key, and save. For VS Code, install an MCP-compatible extension (exact steps depend on the extension), then configure it with your Metabase details. Both tools will then show Metabase as an available tool for the AI to use.

Is it safe to give an AI agent access to Metabase?

It can be safe if you restrict permissions properly. Create a read-only database user with access only to the data the AI needs to see. Set up a Metabase user account with limited permissions. Never give an AI assistant admin credentials or write access. The risk is real (prompt injection, accidental data exposure), but mitigated by least-privilege access controls.

What are the capabilities of the Metabase MCP server?

The AI assistant can query data using Metabase's saved questions and underlying tables, explore the database schema, retrieve results, and create reports. It cannot create dashboards, modify Metabase settings, or execute operations outside of querying and retrieving data. Raw SQL execution is optional and should be disabled for security.

Can I use read-only accounts with the MCP server?

Yes, and you should. Read-only Metabase accounts prevent the AI from accidentally (or maliciously) modifying data or infrastructure. Create a dedicated read-only user for the AI, restrict its table access, and revoke write permissions at both the Metabase and database level.

What permission scopes does the MCP server require?

Minimum: SELECT on specific tables you want the AI to access. The Metabase user account should have read-only permission to only the collections and databases the AI needs. Native query execution should be disabled. You control this entirely through Metabase's permission UI and your database role grants.

How do I enable the MCP server on a self-hosted Metabase?

If you run Metabase yourself (docker, cloud VM, etc.), the process is the same: log in as admin, Settings > AI > toggle Enable MCP Server. If your Metabase version is v0.64+, MCP is available. If it is older, upgrade Metabase or use a community implementation like imlewc/metabase-server (requires additional setup).

The Bottom Line

Metabase MCP gives your AI assistants direct access to your data, eliminating copy-paste and manual reporting. The official server is built in, simple to enable, and free. Security depends entirely on proper permission setup: read-only database users, restricted Metabase accounts, and API key rotation.

If you are running a self-hosted Metabase and want to skip the infrastructure work, consider a managed Metabase hosting service that handles updates and security patches automatically, so you can focus on connecting your data to AI tools. Learn more about hosting options at Opsily's managed Metabase service.