metabase-mcp

A Model Context Protocol (MCP) server for Metabase, designed to run in Claude Code via stdio transport.

Features

• execute tool — Run SQL queries or saved Metabase cards; results returned inline as a formatted table

• export tool — Same as execute, but writes results to CSV or XLSX

• Read-only mode — Blocks mutating SQL keywords and comment-injection by default

• DB whitelist — Restricts queries to an explicit list of allowed database IDs

• Audit log — Appends a JSON line per tool call to a local log file

Related MCP server: Metabase MCP Plus

Setup

1. Install dependencies

cd metabase-mcp
npm install

2. Configure environment

cp .env.example .env
chmod 600 .env

Edit .env and fill in your values:

3. Build

npm run build

4. Add to Claude Code

claude mcp add metabase-mcp -- node /absolute/path/to/metabase-mcp/build/index.js

Replace /absolute/path/to/metabase-mcp with the actual path on your machine.

Tool reference

execute

Run a SQL query or saved card and get results inline.

{
  "mode": "sql",
  "database_id": 1,
  "query": "SELECT id, name FROM users LIMIT 10",
  "row_limit": 100
}

{
  "mode": "card",
  "card_id": 42,
  "card_parameters": [],
  "row_limit": 50
}

export

Write results to a file.

{
  "mode": "sql",
  "database_id": 1,
  "query": "SELECT * FROM orders",
  "format": "csv",
  "filename": "orders_export"
}

{
  "mode": "card",
  "card_id": 7,
  "format": "xlsx"
}

Security model

• Authentication: API key via X-API-KEY header only. No email/password fallback.

• DB whitelist: If METABASE_ALLOWED_DB_IDS is set, any query targeting an unlisted database is blocked before any network call is made.

• Read-only mode: Rejects SQL containing INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE, GRANT, REVOKE (whole-word match) and comment syntax (--, /*, */).

• Path traversal: Export filenames are sanitized and the resolved path is checked to ensure it stays within EXPORT_DIRECTORY.

Error categories