Skip to main content
Glama
jerichosequitin

Metabase

by jerichosequitin
OverviewSchemaRelated ServersScoreDiscussions
TypeScript

Metabase MCP

Ask DeepWiki npm version License: MIT Node.js TypeScript GitHub stars

Buy Me A Coffee

A high-performance Model Context Protocol server for AI integration with Metabase analytics platforms. Features response optimization, robust error handling, and comprehensive data access tools.

Key Features

  • Response Optimization: Up to 90% token reduction for efficient AI context usage

  • Robust Error Handling: Comprehensive error handling with structured, actionable responses

  • Smart Caching: Multi-layer caching with configurable TTL for improved performance

  • Modern MCP Support: MCP 2026-07-28 discovery and cache hints with legacy client compatibility

  • Unified Commands: list, retrieve, search, execute, and export tools

  • Dual Authentication: API key or email/password authentication

  • Large Data Export: Export up to 1M rows in CSV, JSON, and XLSX formats

  • Read-Only Mode: Enabled by default to restrict execute to SELECT queries only

Related MCP server: FastAPI MCP Server

Installation

Option 1: Claude Desktop

Install directly from the Claude Desktop Directory, or:

  1. Download metabase-mcp.mcpb from Releases

  2. Open the .mcpb file with Claude Desktop to install

  3. Configure your Metabase credentials in Claude Desktop's extension settings

Option 2: Manual Configuration

Add the following to your MCP client configuration:

{
  "mcpServers": {
    "metabase-mcp": {
      "command": "npx",
      "args": ["-y", "@jerichosequitin/metabase-mcp"],
      "env": {
        // Required
        "METABASE_URL": "https://your-metabase-instance.com",

        // Authentication (choose one)
        "METABASE_API_KEY": "your_api_key_here",       // API key (recommended)
        "METABASE_USER_EMAIL": "",                     // OR email/password
        "METABASE_PASSWORD": "",

        // Optional (defaults shown)
        "EXPORT_DIRECTORY": "~/Downloads/Metabase",    // Export location
        "METABASE_PROXY_AUTHORIZATION": "",            // Optional Proxy-Authorization value for IAP, e.g. "Bearer <token>"
        "METABASE_READ_ONLY_MODE": "true",             // Restrict to SELECT queries
        "LOG_LEVEL": "info",                           // debug, info, warn, error, fatal (debug enables pretty JSON)
        "CACHE_TTL_MS": "600000",                      // 10 minutes
        "REQUEST_TIMEOUT_MS": "600000"                 // 10 minutes
      }
    }
  }
}

Option 3: Docker

For containerized deployments without installing Node.js. Add to your MCP client configuration:

{
  "mcpServers": {
    "metabase-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "-e", "METABASE_URL=https://your-metabase-instance.com",
        "-e", "METABASE_API_KEY=your_api_key",
        // Optional: mount volume for exports
        // "-v", "~/Downloads/Metabase:/home/node/exports",
        "ghcr.io/jerichosequitin/metabase-mcp:latest"
      ]
    }
  }
}

Or build locally: docker build -t metabase-mcp . and use metabase-mcp as the image name.

Required flags: -i (interactive, for MCP stdio), --rm (cleanup), --init (signal handling)

Environment variables: Pass via -e flags. See Manual Configuration for all options. Docker defaults: LOG_LEVEL=info, METABASE_READ_ONLY_MODE=true, EXPORT_DIRECTORY=/home/node/exports.

Available Tools

list

Fetch all records for a resource type with optimized responses returning only essential fields.

  • Models: cards, dashboards, tables, databases, collections

  • Pagination: offset/limit parameters for large datasets

retrieve

Get detailed information for specific items by ID with concurrent processing.

  • Models: card, dashboard, table, database, collection, field

  • Batch Support: Up to 50 IDs per request

  • Pagination: table_offset/table_limit for databases with many tables

search

Search across all Metabase items using the native search API.

  • Filtering: By model type, database ID, or content

  • Options: Search native SQL queries, include dashboard questions

execute

Execute SQL queries or run saved cards with configurable row limits (default: 100, max: 500).

  • SQL Mode: Custom queries with database_id and query

  • Card Mode: Saved cards with card_id and optional card_parameters for filtering

  • Security: Respects Read-Only Mode (blocks INSERT, UPDATE, DELETE, DROP, etc.)

export

Export large datasets up to 1M rows to the configured export directory.

  • Formats: CSV, JSON, XLSX

  • SQL Mode: Export custom query results

  • Card Mode: Export saved card results with optional filtering

  • Note: When using hosted remote deployments (e.g., Glama), exported files are saved inside the container and are inaccessible. Use execute for query results directly, or run locally via npx/Docker for full export functionality.

clear_cache

Clear internal cache with granular control.

  • Targets: Individual model caches, list caches, or bulk operations (all, all-lists, all-individual)

For Developers

Prerequisites

  • Node.js 20.0.0 or higher

  • Active Metabase instance

Setup

git clone https://github.com/jerichosequitin/metabase-mcp.git
cd metabase-mcp
npm install
npm run build

Then configure your MCP client to use the local build:

{
  "mcpServers": {
    "metabase-mcp": {
      "command": "node",
      "args": ["/path/to/metabase-mcp/build/src/index.js"],
      "env": { /* see Manual Configuration for options */ }
    }
  }
}

Debugging

Use the MCP Inspector for development:

npm run inspector

Testing

npm test                 # Run tests
npm run test:coverage    # Coverage report

Building MCPB Package

npm run mcpb:build

Creates metabase-mcp-{version}.mcpb ready for GitHub Releases.

Security

Read-Only Mode is enabled by default (METABASE_READ_ONLY_MODE=true), restricting the execute tool to SELECT queries only. Write operations (INSERT, UPDATE, DELETE, DROP, etc.) are blocked. Set to false to allow write operations.

Authentication: API key authentication is recommended over email/password for production use.

Proxy Authentication: Set METABASE_PROXY_AUTHORIZATION when Metabase is behind a proxy that requires a Proxy-Authorization header, such as Google IAP. The value is passed through exactly as provided, for example Bearer <token>.

License

This project is licensed under the MIT License.

Available Tools

5 tools
clear_cacheA
Idempotent

Clear the internal cache for stored data. Useful for debugging or when you know the data has changed. Supports granular cache clearing for both individual items and list caches.

ParametersJSON Schema
NameRequiredDescriptionDefault
cache_typeNoType of cache to clear: "all" (default - clears all cache types), individual item caches ("cards", "dashboards", "tables", "databases", "collections", "fields"), list caches ("cards-list", "dashboards-list", "tables-list", "databases-list", "collections-list"), or bulk operations ("all-lists", "all-individual")all

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds valuable behavioral context beyond annotations: it explains that clearing is 'granular' for both individual items and list caches, which helps the agent understand the tool's capabilities. While annotations cover idempotency and non-destructive nature, the description provides practical usage context that complements them without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly concise with three sentences that each add distinct value: stating the core purpose, providing usage context, and explaining granular capabilities. No wasted words, and information is front-loaded with the primary function stated first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with comprehensive annotations and full schema coverage, the description provides adequate context about purpose, usage scenarios, and behavioral characteristics. The main gap is the lack of output schema information, but given the tool's relative simplicity and good annotation coverage, the description is mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the input schema already fully documents the single parameter's purpose, enum values, and default. The description mentions 'granular cache clearing for both individual items and list caches' which aligns with but doesn't significantly expand upon the schema's detailed enum descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Clear') and target resource ('internal cache for stored data'), distinguishing it from sibling tools like list, retrieve, or search. It provides additional context about what the cache contains (stored data) and the granularity of clearing operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use the tool ('Useful for debugging or when you know the data has changed'), giving clear context for its application. However, it doesn't specify when NOT to use it or mention alternatives among the sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

executeA
Destructive

Unified command to execute SQL queries or run saved cards against Metabase databases. Use Card mode when existing cards have the needed filters. Use SQL mode for custom queries or when cards lack required filters. Returns up to 500 rows per request - for larger datasets, use the export tool instead. SECURITY WARNING: SQL mode can execute ANY valid SQL including destructive operations (DELETE, UPDATE, DROP, TRUNCATE, ALTER). Use with caution and ensure appropriate database permissions are configured in Metabase. Note: When Read-Only Mode is enabled, write operations will be rejected with an error.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNoSQL query to execute (SQL mode only)
card_idNoID of saved card to execute (card mode only)
row_limitNoMaximum number of rows to return (default: 100, max: 500). For larger datasets, use the export tool.
database_idNoDatabase ID to execute query against (SQL mode only)
card_parametersNoParameters for filtering card results (card mode only). Each parameter must follow Metabase format: {id: "uuid", slug: "param_name", target: ["dimension", ["template-tag", "param_name"]], type: "param_type", value: ["param_value"]}. For dimension targets, value should be an array; scalar values are accepted and auto-wrapped.
native_parametersNoParameters for SQL template variables like {{variable_name}} (SQL mode only)

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds explicit security warnings about destructive SQL operations, mentions read-only mode rejection, and clarifies behavior for both modes. This goes beyond annotations to provide essential safety context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is concise (~150 words), front-loaded with primary purpose, then logically organizes modes, limitations, warnings, and exceptions. Every sentence serves a purpose—no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool complexity (dual modes, security concerns, no output schema), description covers all critical aspects: modes, parameters, row limits (and export alternative), security warning, and read-only mode handling. Leaves no major gaps for safe usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema documents all parameters. Description adds context by explaining the card_parameters format in detail and clarifying mode-specific parameters (e.g., database_id for SQL only). Slightly redundant on row_limit since schema already has bounds, but overall adds value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states it is a 'Unified command to execute SQL queries or run saved cards', specifying verb (execute) and resources (SQL queries, saved cards). Distinguishes two clear modes and sets expectations for row limits, making it highly specific and actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides guidance on when to use Card vs SQL mode based on filter needs, and mentions export tool for larger datasets. However, it does not compare to sibling tools (clear_cache, search, retrieve, list) or state when not to use this tool, leaving room for ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listA
Read-onlyIdempotent

Fetch all records for a single Metabase resource type with highly optimized responses for overview purposes. Retrieves complete lists of cards, dashboards, tables, databases, or collections. Returns only essential identifier fields for efficient browsing and includes intelligent caching for performance. Supports pagination for large datasets exceeding token limits.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of items to return per page. Maximum 1000 items per page. Use with offset for pagination.
modelYesModel type to list ALL records for. Supported models: cards (all questions/queries), dashboards (all dashboards), tables (all database tables), databases (all connected databases), collections (all folders/collections). Only one model type allowed per request for optimal performance.
offsetNoStarting offset for pagination. Use with limit for paginating through large datasets that exceed token limits.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, non-destructive, idempotent, and open-world properties. The description adds valuable behavioral context beyond annotations: 'intelligent caching for performance', 'pagination for large datasets exceeding token limits', and 'returns only essential identifier fields for efficient browsing'. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with core purpose in the first sentence, followed by supporting details. Every sentence adds value: scope of models, return format, performance features, and pagination support. No wasted words or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (list operation with pagination), rich annotations, and 100% schema coverage, the description is largely complete. It explains the tool's optimization approach and caching behavior. The main gap is lack of output schema, but the description partially compensates by stating 'returns only essential identifier fields'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, providing full parameter documentation. The description adds minimal extra semantics, mentioning 'highly optimized responses' and 'intelligent caching' which relate to overall tool behavior rather than parameter specifics. Baseline 3 is appropriate as the schema carries the burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('fetch all records') and resource ('single Metabase resource type'), specifying the exact models supported (cards, dashboards, tables, databases, collections). It distinguishes from siblings like 'search' by emphasizing 'complete lists' for 'overview purposes' rather than filtered results.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool ('for overview purposes', 'efficient browsing', 'highly optimized responses'), but does not explicitly state when not to use it or name alternatives like 'search' or 'retrieve' from the sibling list. It implies usage for bulk retrieval vs. specific lookups.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

retrieveA
Read-onlyIdempotent

Fetch additional details for supported models (Cards, Dashboards, Tables, Databases, Collections, Fields). Supports multiple IDs (max 50 per request) with intelligent concurrent processing and optimized caching. Includes table pagination for large databases exceeding token limits.

ParametersJSON Schema
NameRequiredDescriptionDefault
idsYesArray of IDs to retrieve (1-50 IDs per request). All IDs must be positive integers. For larger datasets, make multiple requests.
modelYesType of model to retrieve. Only one model type allowed per request.
table_limitNoMaximum number of tables to return per page (database model only). Maximum 100 tables per page. Use with table_offset for pagination.
table_offsetNoStarting offset for table pagination (database model only). Use with table_limit for paginating through large databases that exceed token limits.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds valuable behavioral context beyond annotations: 'intelligent concurrent processing', 'optimized caching', and 'table pagination for large databases exceeding token limits'. While annotations cover safety (readOnlyHint, destructiveHint) and idempotency, the description provides practical implementation details that help the agent understand performance characteristics and limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured in three sentences: purpose statement, key capabilities/limitations, and special handling for edge cases. Every sentence adds value without redundancy, and the most important information (what it does) comes first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich annotations (readOnlyHint, openWorldHint, idempotentHint) and comprehensive schema coverage, the description provides good contextual information about capabilities and limitations. The main gap is the absence of an output schema, but the description compensates somewhat by indicating what kind of details will be fetched. For a read-only retrieval tool, this is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the schema already documents all parameters thoroughly. The description mentions 'multiple IDs (max 50 per request)' and 'table pagination for large databases' which aligns with but doesn't significantly expand upon the schema's parameter descriptions. Baseline 3 is appropriate when schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Fetch') and resource ('additional details for supported models') with specific model types listed. It distinguishes from siblings like 'list', 'search', and 'export' by focusing on retrieving details for specific IDs rather than listing, searching, or exporting data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool (fetching details for specific models with IDs) and mentions limitations (max 50 IDs, pagination for large databases). However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation4/5

Most tools have distinct purposes, but 'list' and 'search' could cause some confusion as both are used for finding content, though their descriptions clarify that 'list' is for complete resource overviews while 'search' is for targeted queries. The other tools (clear_cache, execute, export, retrieve) are clearly differentiated in their functions.

Naming Consistency5/5

All tool names follow a consistent verb-based pattern (clear_cache, execute, export, list, retrieve, search) without mixing conventions like camelCase or snake_case. This uniformity makes the tool set predictable and easy to navigate for an agent.

Tool Count5/5

With 6 tools, this server is well-scoped for its purpose of interacting with Metabase, covering core operations like querying, exporting, listing, retrieving details, searching, and cache management. Each tool serves a specific function without unnecessary bloat or gaps.

Completeness4/5

The tool set covers essential CRUD-like operations for Metabase, including data retrieval (execute, list, retrieve, search), export, and cache management. Minor gaps exist, such as no explicit tools for creating or updating Metabase resources (e.g., cards or dashboards), but agents can likely work around this using existing tools like 'execute' for SQL operations.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • FastAPI MCP Server

    purity3
    A
    license
    Not graded
    quality
    D
    maintenance
    A high-performance Model Context Protocol (MCP) server designed for large language models, enabling real-time communication between AI models and applications with support for session management and intelligent tool registration.
    2
    MIT

  • DataPilot MCP Server

    rickyb30
    A
    license
    A
    quality
    D
    maintenance
    A Model Context Protocol server that enables natural language interaction with Snowflake databases through AI guidance, supporting core database operations, warehouse management, and AI-powered data analysis features.
    13
    2
    MIT

  • Simple MCP Data Manager with

    chirayupatel9
    F
    license
    Not graded
    quality
    D
    maintenance
    A Python-based Model Context Protocol server that integrates local AI models for managing data with features like CRUD operations, similarity search, and text analysis.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jerichosequitin/metabase-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server