metabase-mcp-server

A comprehensive MCP server for Metabase with full read/write support -- 46 tools for cards, dashboards, databases, collections, queries, and more.

Quick Start

Using npx

Add to your .mcp.json:

{
  "mcpServers": {
    "metabase": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ruminaider/metabase-mcp-server"],
      "env": {
        "METABASE_URL": "https://your-instance.metabaseapp.com",
        "METABASE_API_KEY": "your-api-key"
      }
    }
  }
}

Using Docker

docker build -t metabase-mcp-server .

{
  "mcpServers": {
    "metabase": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "METABASE_URL", "-e", "METABASE_API_KEY", "metabase-mcp-server"],
      "env": {
        "METABASE_URL": "https://your-instance.metabaseapp.com",
        "METABASE_API_KEY": "your-api-key"
      }
    }
  }
}

Authentication

The server supports three authentication methods, tried in priority order:

Priority	Method	Environment Variables	Notes
1	API Key	METABASE_API_KEY	Recommended. Create one in Metabase Admin > Settings > Authentication > API Keys.
2	Session Token	METABASE_SESSION_TOKEN	Short-lived token from the Metabase API (POST /api/session).
3	Email + Password	METABASE_USER_EMAIL + METABASE_PASSWORD	The server exchanges credentials for a session token on startup.

Configuration

Variable	Required	Description
METABASE_URL	Yes	Metabase instance URL (e.g. https://analytics.example.com)
METABASE_API_KEY	*	API key for authentication
METABASE_SESSION_TOKEN	*	Session token for authentication
METABASE_USER_EMAIL	*	Email for email/password authentication
METABASE_PASSWORD	*	Password (required when METABASE_USER_EMAIL is set)
METABASE_READ_ONLY	No	Set to true to block all write operations (default: false)
METABASE_CACHE_TTL_MS	No	Cache TTL in milliseconds for schema data (default: 600000 / 10 minutes)

* At least one authentication method is required.

Read-Only Mode

Set METABASE_READ_ONLY=true to block all write operations. The server will reject any tool call that would create, update, archive, or delete content, returning a clear error message. This is useful for providing safe, read-only access to your Metabase instance.

Write-protected tools include: create_card, update_card, archive_card, copy_card, create_dashboard, update_dashboard, archive_dashboard, copy_dashboard, update_dashboard_cards, create_collection, update_collection, update_field, revert_revision, toggle_bookmark, and invalidate_cache.

Performance

Response Optimization

All responses are automatically optimized to reduce token usage:

• List responses strip query definitions, visualization settings, creator details, and other metadata -- returning only identifiers and essential fields.
• Detail responses strip result_metadata (column fingerprints), embedding params, permission booleans, and other bloat while keeping functional fields like queries and parameters.
• Query results are flattened from Metabase's {rows: [[v1,v2]], cols: [{name:"a"}]} format into [{"a": v1, "b": v2}] -- eliminating column metadata overhead.
• All responses use compact JSON (no whitespace).

Caching

Schema exploration data is cached in-memory with a configurable TTL (default: 10 minutes):

• Databases, database metadata, schemas, and schema tables
• Tables, table metadata, foreign keys, fields, and field values
• Collection tree

Cards, dashboards, search results, and query results are NOT cached -- these change frequently and staleness causes bugs.

Cache entries expire automatically. Write operations (update_field) invalidate relevant cache entries immediately. Configure TTL with METABASE_CACHE_TTL_MS.

Batch Retrieval

get_card, get_dashboard, and get_table accept either a single ID or an array of IDs:

{ "id": 42 }
{ "id": [42, 43, 44] }

When multiple IDs are passed, requests are executed concurrently (max 5 at a time) with individual error handling -- one failed ID won't abort the batch.

Tools

Cards (Saved Questions) -- 10 tools

Tool	Description
list_cards	List saved questions/cards, with optional category filter
get_card	Get a card by ID or batch-fetch multiple cards by ID array
create_card	Create a new saved question/card
update_card	Update a card's name, description, query, display, or collection
copy_card	Duplicate a saved question/card
execute_card	Execute a saved question and return results (max 2000 rows)
export_card_results	Execute a card and export results as CSV, JSON, or XLSX (up to 1M rows)
get_card_metadata	Get field, database, and table metadata for a card's query
list_card_dashboards	List all dashboards that contain a specific card
archive_card	Archive (soft-delete) a card

Dashboards -- 8 tools

Tool	Description
list_dashboards	List all dashboards, with optional category filter
get_dashboard	Get a dashboard by ID or batch-fetch multiple dashboards by ID array
create_dashboard	Create a new dashboard
update_dashboard	Update a dashboard's name, description, parameters, or collection
copy_dashboard	Duplicate a dashboard, optionally to a different collection
update_dashboard_cards	Set the full list of cards on a dashboard (add, remove, reposition, resize)
archive_dashboard	Archive (soft-delete) a dashboard
get_dashboard_metadata	Get consolidated query metadata for all cards on a dashboard

Databases -- 5 tools

Tool	Description
list_databases	List all connected databases
get_database	Get details for a specific database
get_database_metadata	Get full metadata including all tables, fields, and foreign keys
list_database_schemas	List all schemas in a database
list_schema_tables	List all tables in a specific schema

Tables & Fields -- 7 tools

Tool	Description
list_tables	List all tables across all databases
get_table	Get a table by ID or batch-fetch multiple tables by ID array
get_table_metadata	Get full metadata including fields, foreign keys, and field values
get_table_fks	Get all foreign key relationships for a table
get_field	Get details for a specific field
get_field_values	Get distinct values for a field
update_field	Update a field's display name, description, semantic type, or visibility

Queries -- 3 tools

Tool	Description
execute_query	Execute a native SQL query (max 2000 rows)
export_query_results	Execute a SQL query and export as CSV, JSON, or XLSX (up to 1M rows)
convert_to_native_sql	Convert an MBQL query to native SQL

Collections -- 6 tools

Tool	Description
list_collections	List all collections (folders)
get_collection	Get details for a collection (use "root" for the root collection)
get_collection_items	List items in a collection, with type filtering and pagination
get_collection_tree	Get the full collection hierarchy as a tree
create_collection	Create a new collection
update_collection	Update a collection's name, description, color, or archived status

Search & Activity -- 4 tools

Tool	Description
search	Search across all content types (cards, dashboards, collections, tables, databases)
get_recent_views	Get recently viewed items for the current user
get_current_user	Get details about the currently authenticated user
invalidate_cache	Invalidate cached query results for a database or dashboard

Revisions & Bookmarks -- 3 tools

Tool	Description
get_revisions	Get the revision history for a card or dashboard
revert_revision	Revert a card or dashboard to a previous revision
toggle_bookmark	Add or remove a bookmark on a card, dashboard, or collection

Development

pnpm install       # install dependencies
pnpm build         # compile TypeScript
pnpm test          # run tests
pnpm dev           # watch mode (recompile on change)
pnpm lint          # lint with Biome
pnpm lint:fix      # auto-fix lint issues
pnpm typecheck     # type-check without emitting

Project Structure

src/
  index.ts                   # Entry point (stdio transport)
  server.ts                  # MCP server creation and tool registration
  config.ts                  # Environment variable parsing and auth detection
  services/
    metabase-client.ts       # HTTP client with auth, retry, and error handling
    card-service.ts          # Card (saved question) CRUD and execution
    collection-service.ts    # Collection CRUD and tree navigation
    dashboard-service.ts     # Dashboard CRUD and card management
    database-service.ts      # Database and schema introspection
    query-service.ts         # Raw SQL execution and export
    revision-service.ts      # Revision history, revert, and bookmarks
    search-service.ts        # Cross-content search and activity
    table-service.ts         # Table/field introspection and metadata
    *.test.ts                # Unit tests for each service
  tools/
    index.ts                 # Wires all tool categories into the MCP server
    card-tools.ts            # Card tool definitions
    collection-tools.ts      # Collection tool definitions
    dashboard-tools.ts       # Dashboard tool definitions
    database-tools.ts        # Database tool definitions
    query-tools.ts           # Query tool definitions
    revision-tools.ts        # Revision/bookmark tool definitions
    search-tools.ts          # Search/activity tool definitions
    table-tools.ts           # Table/field tool definitions
  utils/
    batch.ts                 # Concurrent batch processing with configurable concurrency
    cache.ts                 # In-memory TTL cache for schema exploration data
    errors.ts                # Custom error types (AuthenticationError, NotFoundError, etc.)
    logger.ts                # Structured stderr logging (safe for stdio MCP transport)
    read-only-guard.ts       # Write-operation guard for read-only mode
    response.ts              # Response optimization (field stripping, query flattening, compact JSON)
    retry.ts                 # Exponential backoff retry for transient failures

Adding a New Tool

1. Add or extend a service method in src/services/
2. Register the tool in the appropriate src/tools/*-tools.ts file using server.tool()
3. Increment the return count in the registration function
4. If adding a new tool category, import and call the registration function in src/tools/index.ts
5. Run pnpm build && pnpm test to verify

License

MIT