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.
Badge for your README
Markdown
[](/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
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)
- # Metabase MCP
- [](https://deepwiki.com/jerichosequitin/metabase-mcp)
- [](https://www.npmjs.com/package/@jerichosequitin/metabase-mcp)
- [](https://opensource.org/licenses/MIT)
- [](https://nodejs.org/)
- [](https://www.typescriptlang.org/)
- [](https://github.com/jerichosequitin/metabase-mcp/stargazers)
- [](https://buymeacoffee.com/jerichosequitin)
- 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.
- <a href="https://glama.ai/mcp/servers/@jerichosequitin/Metabase">
- <img width="380" height="200" src="https://glama.ai/mcp/servers/@jerichosequitin/Metabase/badge" />
- </a>
- ## 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
- ## Installation
- ### 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:
- ```jsonc
- {
- "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:
- ```jsonc
- {
- "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`.
- ## 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
- ```bash
- 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:
- ```jsonc
- {
- "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](https://github.com/modelcontextprotocol/inspector) for development:
- ```bash
- npm run inspector
- ```
- ### Testing
- ```bash
- npm test # Run tests
- npm run test:coverage # Coverage report
- ```
- ### Building MCPB Package
- ```bash
- 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.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.