Enables AI agents to query databases, manage dashboards, and automate Metabase administration using a headless API-key authentication.
Also known as Serdnaley/metabase-mcp, metabase-mcp, @serdnaley/metabase-mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.5.0
- Last commit
- Nov 14, 2026
- License
- MIT
What is Metabase MCP?
Metabase enables AI agents to query databases, manage dashboards, and automate Metabase administration using a headless API-key authentication.
Summary generated from the project's README
About Metabase MCP server
Metabase MCP provides a headless interface for connecting AI agents, applications, or CI/CD pipelines to Metabase instances. Unlike the standard Metabase MCP which requires OAuth, this server uses a plain API key or email and password for authentication. This makes it suitable for automated environments like containers or servers where interactive browser logins are not possible.
The server offers 187 tools organized into 34 toolsets, covering everything from data querying to full administrative tasks. Users can manage dashboards, collections, users, permissions, and database connections. It supports both local stdio connections for desktop clients like Claude Desktop or Cursor, and remote HTTP deployments using a bearer token for shared services.
To maintain performance and security, the server includes features like toolset filtering, a read-only mode, and result compaction for large datasets. Developers can limit the context sent to the model by enabling only specific toolsets such as query, content, or admin. It is compatible with both Metabase OSS and paid editions, including features like caching and model persistence.
What you can do with it
- 1Automated Data QueryingAn AI agent can search databases and execute queries to retrieve specific datasets.
- 2Headless CI/CD IntegrationRun Metabase tasks in automated pipelines without needing an interactive OAuth flow.
Written from the project's README. Every use case is checked against a quote from it.
How to install Metabase MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Metabase MCP in Claude Code
$ claude mcp add --env 'METABASE_URL=<METABASE_URL>' --env 'METABASE_API_KEY=<YOUR_METABASE_API_KEY>' --env 'METABASE_CUSTOM_HEADERS=<YOUR_METABASE_CUSTOM_HEADERS>' --env 'METABASE_PASSWORD=<YOUR_METABASE_PASSWORD>' metabase-mcp -- npx -y @serdnaley/metabase-mcpInstall Metabase MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"metabase-mcp": {
"command": "npx",
"args": [
"-y",
"@serdnaley/metabase-mcp"
],
"env": {
"METABASE_URL": "<METABASE_URL>",
"METABASE_API_KEY": "<YOUR_METABASE_API_KEY>",
"METABASE_CUSTOM_HEADERS": "<YOUR_METABASE_CUSTOM_HEADERS>",
"METABASE_PASSWORD": "<YOUR_METABASE_PASSWORD>"
}
}
}
}Install Metabase MCP in VS Code
.vscode/mcp.json
{
"servers": {
"metabase-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@serdnaley/metabase-mcp"
],
"env": {
"METABASE_URL": "<METABASE_URL>",
"METABASE_API_KEY": "<YOUR_METABASE_API_KEY>",
"METABASE_CUSTOM_HEADERS": "<YOUR_METABASE_CUSTOM_HEADERS>",
"METABASE_PASSWORD": "<YOUR_METABASE_PASSWORD>"
}
}
}
}Install Metabase MCP in VS Code CLI
$ code --add-mcp '{"name":"metabase-mcp","type":"stdio","command":"npx","args":["-y","@serdnaley/metabase-mcp"],"env":{"METABASE_URL":"<METABASE_URL>","METABASE_API_KEY":"<YOUR_METABASE_API_KEY>","METABASE_CUSTOM_HEADERS":"<YOUR_METABASE_CUSTOM_HEADERS>","METABASE_PASSWORD":"<YOUR_METABASE_PASSWORD>"}}'Install Metabase MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"metabase-mcp": {
"command": "npx",
"args": [
"-y",
"@serdnaley/metabase-mcp"
],
"env": {
"METABASE_URL": "<METABASE_URL>",
"METABASE_API_KEY": "<YOUR_METABASE_API_KEY>",
"METABASE_CUSTOM_HEADERS": "<YOUR_METABASE_CUSTOM_HEADERS>",
"METABASE_PASSWORD": "<YOUR_METABASE_PASSWORD>"
}
}
}
}Install Metabase MCP in Codex
$ codex mcp add metabase-mcp --env 'METABASE_URL=<METABASE_URL>' --env 'METABASE_API_KEY=<YOUR_METABASE_API_KEY>' --env 'METABASE_CUSTOM_HEADERS=<YOUR_METABASE_CUSTOM_HEADERS>' --env 'METABASE_PASSWORD=<YOUR_METABASE_PASSWORD>' -- npx -y @serdnaley/metabase-mcpInstall Metabase MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.metabase-mcp] command = "npx" args = ["-y", "@serdnaley/metabase-mcp"] [mcp_servers.metabase-mcp.env] METABASE_URL = "<METABASE_URL>" METABASE_API_KEY = "<YOUR_METABASE_API_KEY>" METABASE_CUSTOM_HEADERS = "<YOUR_METABASE_CUSTOM_HEADERS>" METABASE_PASSWORD = "<YOUR_METABASE_PASSWORD>"
Install Metabase MCP in Gemini CLI
$ gemini mcp add -s user -e 'METABASE_URL=<METABASE_URL>' -e 'METABASE_API_KEY=<YOUR_METABASE_API_KEY>' -e 'METABASE_CUSTOM_HEADERS=<YOUR_METABASE_CUSTOM_HEADERS>' -e 'METABASE_PASSWORD=<YOUR_METABASE_PASSWORD>' metabase-mcp npx -- -y @serdnaley/metabase-mcpInstall Metabase MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"metabase-mcp": {
"command": "npx",
"args": [
"-y",
"@serdnaley/metabase-mcp"
],
"env": {
"METABASE_URL": "<METABASE_URL>",
"METABASE_API_KEY": "<YOUR_METABASE_API_KEY>",
"METABASE_CUSTOM_HEADERS": "<YOUR_METABASE_CUSTOM_HEADERS>",
"METABASE_PASSWORD": "<YOUR_METABASE_PASSWORD>"
}
}
}
}Configuration
METABASE_URLRequiredMetabase base URL, e.g. https://metabase.example.com
METABASE_API_KEYSecretMetabase API key (or set METABASE_EMAIL + METABASE_PASSWORD)
METABASE_CUSTOM_HEADERSSecretExtra headers for every Metabase request (e.g. Cloudflare Access)
METABASE_PASSWORDSecretLogin password (alternative to an API key)
MCP_HTTP_TOKENMCP_TRANSPORTMETABASE_EMAILLogin email (alternative to an API key)
METABASE_READ_ONLY_MODEtrue hides all write tools
METABASE_TOOLSETSComma list of toolsets or presets (all, query, content, admin)
METABASE_TOOLS_DISABLETools to disable (names or globs); always wins
METABASE_TOOLS_ENABLEExtra tools to enable (names or globs)
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableserdnaley/metabase-mcp is public and reachablegithub.com/serdnaley/metabase-mcp ↗Pass
- Package names this repository as its source@serdnaley/metabase-mcp names serdnaley/metabase-mcp as sourcenpmjs.com/package/@serdnaley/metabase-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @serdnaley/metabase-mcpnpmjs.com/package/@serdnaley/metabase-mcp/v/0.5.0#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/serdnaley/metabase-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @serdnaley/metabase-mcpPass
- No critical advisory in the package or its dependencies101 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@serdnaley/metabase-mcp
The headless MCP server for Metabase. Plug Metabase into any AI agent, app, CI job or server with a plain API key: no OAuth flow, no browser, no admin switch to flip.
- Headless auth. A Metabase API key (or email/password) is all it needs. That works where an interactive OAuth login can't: servers, CI, containers, your own app or agent. Metabase's built-in MCP is documented as OAuth-only and needs an admin to enable it on 0.60+.
- Runs locally or as a service. stdio for desktop clients, or Streamable HTTP with a bearer token for shared and server deployments. Metabase credentials stay on the server.
- Full coverage. 187 tools for querying and for running Metabase: dashboards, questions, collections, users, groups, permissions, databases, settings, alerts, transforms, exports and more.
- Only the tools you need. Toolsets and per-tool enable/disable keep the model's context small. Every tool carries read-only/destructive hints, so clients can auto-approve reads.
- Any Metabase. Works with Metabase OSS (free) and paid editions, tested against 0.59 and 0.64. Paid-only features (caching, model persistence, moderation) work when your instance has them; CI covers the free edition.
How it compares with Metabase's built-in MCP and other Metabase MCP servers: docs/comparison.md. Full tool catalog: serdnaley.github.io/metabase-mcp.
Features
- 187 MCP tools across 34 toolsets: search, databases, tables, collections, cards, dashboards, actions, dataset, users, groups, permissions, segments, revisions, settings, alerts, subscriptions, glossary, documents, timelines, bookmarks, moderation, snippets, x-rays, cache, persistence, uploads, metrics, measures, transforms, exports, API keys, embedding, tasks & logs, explorations
- Toolsets: load only what you need (
METABASE_TOOLSETS=query), add or drop single tools with globs - Tool annotations:
readOnlyHint/destructiveHint/idempotentHinton every tool - stdio or HTTP: Streamable HTTP with bearer auth for shared deployments
- Read-only mode: hide every write tool with one env var
- Large-result safety: compact query results, row and response-size caps, paging
- Resources & prompts: browse databases, cards, dashboards and collections; ready-made workflows
- Admin automation: users, groups, permissions, settings, database connections, transforms
- Type-safe: HTTP client generated from Metabase's OpenAPI spec
- Zero config: runs via
npx, no installation needed
Installation
Download metabase-mcp-X.Y.Z.mcpb from the latest release and open it: Claude Desktop shows a form for the Metabase URL and API key. No Node.js setup or JSON editing.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"metabase": {
"command": "npx",
"args": ["-y", "@serdnaley/metabase-mcp"],
"env": {
"METABASE_URL": "https://your-metabase.example.com",
"METABASE_API_KEY": "mb_xxx"
}
}
}
}
Restart Claude Desktop after saving.
claude mcp add metabase \
--env METABASE_URL=https://your-metabase.example.com \
--env METABASE_API_KEY=mb_xxx \
-- npx -y @serdnaley/metabase-mcp
Or add to .claude/mcp.json:
{
"mcpServers": {
"metabase": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@serdnaley/metabase-mcp"],
"env": {
"METABASE_URL": "https://your-metabase.example.com",
"METABASE_API_KEY": "mb_xxx"
}
}
}
}
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):
{
"mcpServers": {
"metabase": {
"command": "npx",
"args": ["-y", "@serdnaley/metabase-mcp"],
"env": {
"METABASE_URL": "https://your-metabase.example.com",
"METABASE_API_KEY": "mb_xxx"
}
}
}
}
Restart Cursor after saving.
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"metabase": {
"command": "npx",
"args": ["-y", "@serdnaley/metabase-mcp"],
"env": {
"METABASE_URL": "https://your-metabase.example.com",
"METABASE_API_KEY": "mb_xxx"
}
}
}
}
Add to your Cline MCP settings (accessible via the MCP Servers icon):
{
"mcpServers": {
"metabase": {
"command": "npx",
"args": ["-y", "@serdnaley/metabase-mcp"],
"env": {
"METABASE_URL": "https://your-metabase.example.com",
"METABASE_API_KEY": "mb_xxx"
}
}
}
}
Add to .continue/config.yaml:
mcpServers:
- name: metabase
command: npx
args:
- "-y"
- "@serdnaley/metabase-mcp"
env:
METABASE_URL: "https://your-metabase.example.com"
METABASE_API_KEY: "mb_xxx"
Add to your Zed settings.json:
{
"context_servers": {
"metabase": {
"command": "npx",
"args": ["-y", "@serdnaley/metabase-mcp"],
"env": {
"METABASE_URL": "https://your-metabase.example.com",
"METABASE_API_KEY": "mb_xxx"
}
}
}
}
Run the server once in HTTP mode (see HTTP mode), then point clients at it. Claude Code:
claude mcp add --transport http metabase https://mcp.example.com/mcp \
--header "Authorization: Bearer $MCP_HTTP_TOKEN"
Generic JSON config (Cursor, VS Code and others):
{
"mcpServers": {
"metabase": {
"url": "https://mcp.example.com/mcp",
"headers": { "Authorization": "Bearer <MCP_HTTP_TOKEN>" }
}
}
}
Configuration
| Variable | Required | Description |
|---|---|---|
METABASE_URL |
Yes | Base URL of your Metabase instance |
METABASE_API_KEY |
No* | API key for authentication |
METABASE_EMAIL |
No* | Email for session-based auth |
METABASE_PASSWORD |
No* | Password for session-based auth |
METABASE_READ_ONLY_MODE |
No | Set to true to disable write tools |
METABASE_CUSTOM_HEADERS |
No | Extra HTTP headers sent on every request, including the session login (see below) |
METABASE_TOOLSETS |
No | Comma list of toolsets or presets to load (default: all). See Toolsets |
METABASE_TOOLS_ENABLE |
No | Extra tools to load on top of the toolsets (names or globs, e.g. get_card,export_*) |
METABASE_TOOLS_DISABLE |
No | Tools never to load (names or globs); always wins over enable |
METABASE_MAX_ROWS |
No | Row cap for query tools (default 500); see Large results |
METABASE_MAX_RESPONSE_CHARS |
No | Size cap for any tool response (default 100000) |
MCP_TRANSPORT |
No | stdio (default) or http. --http on the command line does the same |
MCP_HTTP_HOST / MCP_HTTP_PORT |
No | HTTP bind address, default 127.0.0.1:3333 (PORT also works) |
MCP_HTTP_TOKEN |
HTTP mode | Bearer token clients must send (min. 16 chars) |
MCP_HTTP_ALLOW_NO_AUTH |
No | true runs HTTP without a token, only on a loopback host |
*Either METABASE_API_KEY or both METABASE_EMAIL + METABASE_PASSWORD must be provided. API key is recommended.
Custom headers
Use METABASE_CUSTOM_HEADERS when Metabase sits behind a proxy that needs its own headers, such as Cloudflare Access service tokens. Give it a JSON object:
METABASE_CUSTOM_HEADERS='{"CF-Access-Client-Id": "xxx.access", "CF-Access-Client-Secret": "yyy"}'
or Name: value pairs separated by newlines or ;:
METABASE_CUSTOM_HEADERS='CF-Access-Client-Id: xxx.access; CF-Access-Client-Secret: yyy'
The auth headers (X-API-Key, X-Metabase-Session) always win over a custom header with the same name. A malformed value stops the server at startup.
Toolsets
Each tool domain is a toolset (dashboards, users, transforms, ...; the full list is in Tools). Presets bundle them:
| Preset | For |
|---|---|
all |
everything (default) |
query |
exploring and querying data: search, databases, tables, dataset, cards, metrics, measures, segments, exports, activity, x-rays, explorations |
content |
building and organising content: collections, cards, dashboards, documents, snippets, timelines, alerts, ... |
admin |
running the instance: users, permissions, settings, databases, tables, cache, uploads, transforms, actions, ... |
METABASE_TOOLSETS=query,dashboards # analyst assistant
METABASE_TOOLS_ENABLE=create_card # plus one write tool
METABASE_TOOLS_DISABLE='delete_*' # never delete anything
Precedence, strongest first: read-only mode > METABASE_TOOLS_DISABLE > METABASE_TOOLS_ENABLE > METABASE_TOOLSETS. An unknown toolset stops the server at startup; an enable/disable pattern that matches nothing logs a warning. The startup log (stderr) shows how many tools are enabled.
Large results
Query tools (execute_query, execute_card_query, run_metric) return a compact view: columns
(name, type) and rows, without Metabase's column internals, results_metadata and insights. Pass
verbose: true for the raw response. Results are capped at METABASE_MAX_ROWS rows (per call:
max_rows, never above the cap) and paged with offset; a note says how to get the rest. Every tool
response is compact JSON capped at METABASE_MAX_RESPONSE_CHARS. For a 10 / 100 / 500-row
SELECT * FROM ORDERS this is 94% / 76% / 60% smaller than the raw pretty-printed response. For
full result sets use the export tools with output_path.
Resources and prompts
Besides tools the server offers MCP resources for browsing (compact JSON):
metabase://databases, metabase://database/{id}/schema, metabase://card/{id},
metabase://dashboard/{id}, metabase://collection/{id} (root for the root collection), and
prompts for common workflows: explore-database, build-dashboard, explain-card,
audit-permissions. Both follow the tool selection: a resource needs its toolset, a prompt needs
every tool it uses (so build-dashboard disappears in read-only mode).
HTTP mode (shared / server deployments)
METABASE_URL=https://metabase.example.com \
METABASE_API_KEY=mb_xxx \
MCP_TRANSPORT=http MCP_HTTP_HOST=0.0.0.0 MCP_HTTP_PORT=3333 \
MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
npx -y @serdnaley/metabase-mcp
Clients connect to http://<host>:3333/mcp with Authorization: Bearer <MCP_HTTP_TOKEN>. GET /health answers without auth and reveals nothing. The endpoint is stateless (no sessions), so it scales horizontally. Put it behind TLS (a reverse proxy) when it leaves localhost. Everyone with the token acts as the Metabase API key's user, so give each audience its own key, token and toolsets.
Or as a container (ghcr.io/serdnaley/metabase-mcp, amd64 + arm64, HTTP mode by default):
docker run -p 3333:3333 \
-e METABASE_URL=https://metabase.example.com -e METABASE_API_KEY=mb_xxx \
-e MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
ghcr.io/serdnaley/metabase-mcp
Getting a Metabase API Key
- Go to your Metabase instance
- Click the gear icon > Admin settings > Authentication > API Keys
- Click "Create API Key"
- Give it a name and select the appropriate group (e.g., Administrators)
- Copy the key — it starts with
mb_
Examples
"Create a dashboard showing order trends"
The AI assistant will:
- Use
searchandget_database_metadatato discover your data - Use
create_cardto create questions (e.g., orders by month, revenue by product) - Use
create_dashboardto create the dashboard - Use
update_dashboard_cardsto arrange the cards with a layout
"Move all Q4 reports to the Archive collection"
The AI assistant will:
- Use
searchto find Q4 report cards - Use
create_collectionto create an Archive collection if needed - Use
update_cardon each card to move it to the new collection
"What tables do we have in the analytics database?"
The AI assistant will:
- Use
list_databasesto find the database - Use
get_database_metadatato list all tables, fields, and relationships
Tools
Full catalog with parameters: see the tool catalog site (generated from the code).
Read tools (83, always available)
| Toolset | Tools |
|---|---|
Search (search) |
search |
Databases (databases) |
list_databases, get_database, get_database_metadata, list_database_schemas, get_database_schema |
Tables & Fields (tables) |
get_table, get_table_query_metadata, get_field, get_field_values |
Collections (collections) |
get_collection_tree, list_collections, get_collection, list_collection_items |
Cards (cards) |
list_cards, get_card, execute_card_query |
Dashboards (dashboards) |
list_dashboards, get_dashboard |
Actions (actions) |
list_actions, get_action |
Dataset (ad-hoc queries) (dataset) |
execute_query |
Users & Groups (users) |
list_users, get_user, get_current_user, list_groups, get_group |
Permissions (permissions) |
get_permissions_graph, get_collection_permissions |
Segments (segments) |
list_segments, get_segment |
Revisions (revisions) |
list_revisions |
Settings (settings) |
list_settings, get_setting |
Alerts & Subscriptions (notifications) |
list_alerts, get_alert, list_dashboard_subscriptions, list_notifications |
X-Rays (xrays) |
generate_xray |
Activity & Tasks (activity) |
get_activity, get_recent_items, get_popular_items |
Snippets (snippets) |
list_snippets, get_snippet |
Glossary (glossary) |
list_glossary_terms, get_glossary_term |
Documents (documents) |
list_documents, get_document |
Timelines (timelines) |
list_timelines, get_timeline |
Bookmarks (bookmarks) |
list_bookmarks |
EID Translation (eid-translation) |
translate_entity_ids |
Metrics (metrics) |
list_metrics, get_metric, run_metric, list_metric_dimensions, get_metric_dimension_values |
Measures (measures) |
list_measures, get_measure |
Transforms (transforms) |
list_transforms, get_transform, list_transform_runs, get_transform_run, list_transform_jobs, list_transform_tags |
Exports (exports) |
export_card_query, export_query, export_dashboard_pdf |
API Keys (api-keys) |
list_api_keys |
Embedding (embedding) |
get_embedding_status, create_embed_url |
Tasks & Logs (diagnostics) |
list_tasks, get_task, list_task_types, list_task_runs, get_scheduler_info, get_server_logs, list_log_presets, get_premium_token_status |
Explorations (explorations) |
list_exploration_dimensions, list_my_explorations, get_exploration, get_exploration_query_result |
Write tools (104, hidden in read-only mode)
| Toolset | Tools |
|---|---|
Databases (databases) |
create_database, update_database, delete_database, validate_database, sync_database_schema |
Tables & Fields (tables) |
update_table, update_field, rescan_field_values, discard_field_values, reorder_fields |
Collections (collections) |
create_collection, update_collection |
Cards (cards) |
create_card, update_card, delete_card, copy_card, create_card_public_link, delete_card_public_link |
Dashboards (dashboards) |
create_dashboard, update_dashboard, delete_dashboard, copy_dashboard, update_dashboard_cards, create_dashboard_public_link, delete_dashboard_public_link |
Actions (actions) |
create_action, update_action, delete_action, execute_action, create_action_public_link, delete_action_public_link |
Users & Groups (users) |
create_user, update_user, deactivate_user, reactivate_user, create_group, update_group, delete_group, add_group_member, remove_group_member |
Permissions (permissions) |
update_permissions_graph, update_collection_permissions |
Segments (segments) |
create_segment, update_segment, delete_segment |
Revisions (revisions) |
revert_revision |
Settings (settings) |
update_setting |
Alerts & Subscriptions (notifications) |
send_notification, create_alert, update_alert, delete_alert, create_dashboard_subscription, update_dashboard_subscription, delete_dashboard_subscription |
Cache (cache) |
invalidate_cache, update_cache_config |
Model Persistence (persistence) |
persist_model, unpersist_model, refresh_persisted_model |
Uploads (upload) |
upload_csv |
Snippets (snippets) |
create_snippet, update_snippet, delete_snippet |
Glossary (glossary) |
create_glossary_term, update_glossary_term, delete_glossary_term |
Documents (documents) |
create_document, update_document, delete_document |
Timelines (timelines) |
create_timeline, update_timeline, delete_timeline, create_timeline_event, update_timeline_event, delete_timeline_event |
Bookmarks (bookmarks) |
create_bookmark, delete_bookmark |
Moderation (moderation) |
create_moderation_review |
Metrics (metrics) |
create_metric, update_metric |
Measures (measures) |
create_measure, update_measure |
Transforms (transforms) |
create_transform, update_transform, delete_transform, run_transform, cancel_transform_run, create_transform_job, run_transform_job, delete_transform_job, create_transform_tag |
API Keys (api-keys) |
create_api_key, update_api_key, regenerate_api_key, delete_api_key |
Embedding (embedding) |
set_static_embedding, set_resource_embedding |
Tasks & Logs (diagnostics) |
set_log_levels, reset_log_levels |
Explorations (explorations) |
create_exploration, update_exploration, delete_exploration, restart_exploration_thread, cancel_exploration_thread |
Presets for METABASE_TOOLSETS: all (everything); query (search, databases, tables, dataset, cards, metrics, measures, segments, exports, activity, xrays, explorations); content (search, collections, cards, dashboards, documents, snippets, timelines, bookmarks, glossary, revisions, moderation, notifications, exports); admin (users, permissions, settings, databases, tables, cache, persistence, upload, transforms, actions, activity, eid-translation, api-keys, embedding, diagnostics).
Security
execute_query is available even in read-only mode. It can execute arbitrary SQL against any database the configured Metabase account has access to. Metabase enforces its own permission model, but this tool does not add additional restrictions.
To prevent write operations, ensure the Metabase API key or account has read-only database permissions within Metabase itself.
Exports can write local files. export_card_query, export_query and export_dashboard_pdf stay available in read-only mode (they only read from Metabase) and, when given output_path, write to that absolute path on the machine running the MCP server. They never overwrite an existing file unless overwrite: true is passed. Metabase applies the same access check to an export as to running the query; its separate "Download results" permission exists only on Pro/Enterprise.
Read-only mode is not a security boundary. METABASE_READ_ONLY_MODE only hides write tools. What a key can really do is set in Metabase: an API key gets the permissions of its group plus All Users. For a read-only assistant, put the key in a group with View-only collection access and "Create queries" set to query builder only (or no), and restrict All Users to no more than that. See docs/read-only-and-permissions.md for the probe results and a setup checklist.
HTTP mode requires a bearer token. MCP_TRANSPORT=http refuses to start without MCP_HTTP_TOKEN (compared in constant time), unless MCP_HTTP_ALLOW_NO_AUTH=true on a loopback host, where Host-header checks block DNS rebinding. The token grants everything the configured Metabase key can do, so treat it like that key and serve the endpoint over TLS outside localhost.
Raw SQL is one-click. Read tools are marked readOnlyHint: true, including execute_query and export_query, so clients can auto-approve them. ⚠️ Their SQL is sent as-is: this server does not block INSERT/UPDATE/DELETE/DDL, and both tool descriptions say so. Use a Metabase API key whose group cannot run native queries (or a database user with read-only grants) if SQL must not write — see docs/read-only-and-permissions.md.
Action types are restricted. The create_action tool only allows query and implicit action types. HTTP actions (which could make arbitrary outbound requests) are blocked.
Development
bun install
bun run dev # Start the MCP server
bun run build # Build for npm
bun run generate-types # Regenerate types from Metabase OpenAPI spec
Metabase MCP questions
How do I add Metabase MCP to Claude Code?
Run claude mcp add --env 'METABASE_URL=<METABASE_URL>' --env 'METABASE_API_KEY=<YOUR_METABASE_API_KEY>' --env 'METABASE_CUSTOM_HEADERS=<YOUR_METABASE_CUSTOM_HEADERS>' --env 'METABASE_PASSWORD=<YOUR_METABASE_PASSWORD>' metabase-mcp -- npx -y @serdnaley/metabase-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Metabase MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does this server support OAuth?
No, this is a headless implementation that uses a Metabase API key or email/password for authentication, making it suitable for CI and servers.