Skip to content
Back to search

metabase-mcp

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. Featured on Claude.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jerichosequitin--metabase-mcp/badge.svg)](/listings/jerichosequitin--metabase-mcp)

HTML

<a href="/listings/jerichosequitin--metabase-mcp"><img src="/api/listings/jerichosequitin--metabase-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option 1: Claude Desktop

Install directly from the [Claude Desktop Directory](https://claude.ai/directory/connectors/ant.dir.gh.jerichosequitin.metabase), or:

1. Download `metabase-mcp.mcpb` from [Releases](https://github.com/jerichosequitin/metabase-mcp/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](#option-2-manual-configuration) for all options. Docker defaults: `LOG_LEVEL=info`, `METABASE_READ_ONLY_MODE=true`, `EXPORT_DIRECTORY=/home/node/exports`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 196 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Metabase MCP
  2. [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/jerichosequitin/metabase-mcp)
  3. [![npm version](https://img.shields.io/npm/v/@jerichosequitin/metabase-mcp)](https://www.npmjs.com/package/@jerichosequitin/metabase-mcp)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
  5. [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20.0.0-brightgreen?logo=node.js&logoColor=white)](https://nodejs.org/)
  6. [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
  7. [![GitHub stars](https://img.shields.io/github/stars/jerichosequitin/metabase-mcp)](https://github.com/jerichosequitin/metabase-mcp/stargazers)
  8. [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/jerichosequitin)
  9. 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.
  10. <a href="https://glama.ai/mcp/servers/@jerichosequitin/Metabase">
  11. <img width="380" height="200" src="https://glama.ai/mcp/servers/@jerichosequitin/Metabase/badge" />
  12. </a>
  13. ## Key Features
  14. - **Response Optimization**: Up to 90% token reduction for efficient AI context usage
  15. - **Robust Error Handling**: Comprehensive error handling with structured, actionable responses
  16. - **Smart Caching**: Multi-layer caching with configurable TTL for improved performance
  17. - **Modern MCP Support**: MCP `2026-07-28` discovery and cache hints with legacy client compatibility
  18. - **Unified Commands**: `list`, `retrieve`, `search`, `execute`, and `export` tools
  19. - **Dual Authentication**: API key or email/password authentication
  20. - **Large Data Export**: Export up to 1M rows in CSV, JSON, and XLSX formats
  21. - **Read-Only Mode**: Enabled by default to restrict execute to SELECT queries only
  22. ## Installation
  23. ### Option 1: Claude Desktop
  24. Install directly from the [Claude Desktop Directory](https://claude.ai/directory/connectors/ant.dir.gh.jerichosequitin.metabase), or:
  25. 1. Download `metabase-mcp.mcpb` from [Releases](https://github.com/jerichosequitin/metabase-mcp/releases)
  26. 2. Open the `.mcpb` file with Claude Desktop to install
  27. 3. Configure your Metabase credentials in Claude Desktop's extension settings
  28. ### Option 2: Manual Configuration
  29. Add the following to your MCP client configuration:
  30. ```jsonc
  31. {
  32. "mcpServers": {
  33. "metabase-mcp": {
  34. "command": "npx",
  35. "args": ["-y", "@jerichosequitin/metabase-mcp"],
  36. "env": {
  37. // Required
  38. "METABASE_URL": "https://your-metabase-instance.com",
  39. // Authentication (choose one)
  40. "METABASE_API_KEY": "your_api_key_here", // API key (recommended)
  41. "METABASE_USER_EMAIL": "", // OR email/password
  42. "METABASE_PASSWORD": "",
  43. // Optional (defaults shown)
  44. "EXPORT_DIRECTORY": "~/Downloads/Metabase", // Export location
  45. "METABASE_PROXY_AUTHORIZATION": "", // Optional Proxy-Authorization value for IAP, e.g. "Bearer <token>"
  46. "METABASE_READ_ONLY_MODE": "true", // Restrict to SELECT queries
  47. "LOG_LEVEL": "info", // debug, info, warn, error, fatal (debug enables pretty JSON)
  48. "CACHE_TTL_MS": "600000", // 10 minutes
  49. "REQUEST_TIMEOUT_MS": "600000" // 10 minutes
  50. }
  51. }
  52. }
  53. }
  54. ```
  55. ### Option 3: Docker
  56. For containerized deployments without installing Node.js. Add to your MCP client configuration:
  57. ```jsonc
  58. {
  59. "mcpServers": {
  60. "metabase-mcp": {
  61. "command": "docker",
  62. "args": [
  63. "run", "-i", "--rm", "--init",
  64. "-e", "METABASE_URL=https://your-metabase-instance.com",
  65. "-e", "METABASE_API_KEY=your_api_key",
  66. // Optional: mount volume for exports
  67. // "-v", "~/Downloads/Metabase:/home/node/exports",
  68. "ghcr.io/jerichosequitin/metabase-mcp:latest"
  69. ]
  70. }
  71. }
  72. }
  73. ```
  74. Or build locally: `docker build -t metabase-mcp .` and use `metabase-mcp` as the image name.
  75. **Required flags:** `-i` (interactive, for MCP stdio), `--rm` (cleanup), `--init` (signal handling)
  76. **Environment variables:** Pass via `-e` flags. See [Manual Configuration](#option-2-manual-configuration) for all options. Docker defaults: `LOG_LEVEL=info`, `METABASE_READ_ONLY_MODE=true`, `EXPORT_DIRECTORY=/home/node/exports`.
  77. ## Available Tools
  78. ### `list`
  79. Fetch all records for a resource type with optimized responses returning only essential fields.
  80. - **Models**: `cards`, `dashboards`, `tables`, `databases`, `collections`
  81. - **Pagination**: `offset`/`limit` parameters for large datasets
  82. ### `retrieve`
  83. Get detailed information for specific items by ID with concurrent processing.
  84. - **Models**: `card`, `dashboard`, `table`, `database`, `collection`, `field`
  85. - **Batch Support**: Up to 50 IDs per request
  86. - **Pagination**: `table_offset`/`table_limit` for databases with many tables
  87. ### `search`
  88. Search across all Metabase items using the native search API.
  89. - **Filtering**: By model type, database ID, or content
  90. - **Options**: Search native SQL queries, include dashboard questions
  91. ### `execute`
  92. Execute SQL queries or run saved cards with configurable row limits (default: 100, max: 500).
  93. - **SQL Mode**: Custom queries with `database_id` and `query`
  94. - **Card Mode**: Saved cards with `card_id` and optional `card_parameters` for filtering
  95. - **Security**: Respects Read-Only Mode (blocks INSERT, UPDATE, DELETE, DROP, etc.)
  96. ### `export`
  97. Export large datasets up to 1M rows to the configured export directory.
  98. - **Formats**: CSV, JSON, XLSX
  99. - **SQL Mode**: Export custom query results
  100. - **Card Mode**: Export saved card results with optional filtering
  101. - **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.
  102. ### `clear_cache`
  103. Clear internal cache with granular control.
  104. - **Targets**: Individual model caches, list caches, or bulk operations (`all`, `all-lists`, `all-individual`)
  105. ## For Developers
  106. ### Prerequisites
  107. - Node.js 20.0.0 or higher
  108. - Active Metabase instance
  109. ### Setup
  110. ```bash
  111. git clone https://github.com/jerichosequitin/metabase-mcp.git
  112. cd metabase-mcp
  113. npm install
  114. npm run build
  115. ```
  116. Then configure your MCP client to use the local build:
  117. ```jsonc
  118. {
  119. "mcpServers": {
  120. "metabase-mcp": {
  121. "command": "node",
  122. "args": ["/path/to/metabase-mcp/build/src/index.js"],
  123. "env": { /* see Manual Configuration for options */ }
  124. }
  125. }
  126. }
  127. ```
  128. ### Debugging
  129. Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for development:
  130. ```bash
  131. npm run inspector
  132. ```
  133. ### Testing
  134. ```bash
  135. npm test # Run tests
  136. npm run test:coverage # Coverage report
  137. ```
  138. ### Building MCPB Package
  139. ```bash
  140. npm run mcpb:build
  141. ```
  142. Creates `metabase-mcp-{version}.mcpb` ready for GitHub Releases.
  143. ## Security
  144. **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.
  145. **Authentication**: API key authentication is recommended over email/password for production use.
  146. **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>`.
  147. ## License
  148. This project is licensed under the MIT License.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.