Back to search
mcp-metabase-server
MCP serverGitHub
A comprehensive MCP server for Metabase with 70+ tools.
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
Markdown
[](/listings/easecloudio--mcp-metabase-server)HTML
<a href="/listings/easecloudio--mcp-metabase-server"><img src="/api/listings/easecloudio--mcp-metabase-server/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.
export METABASE_URL=https://your-metabase-instance.com export METABASE_API_KEY=your_metabase_api_key npx @easecloudio/mcp-metabase-server
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 · 469 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Metabase MCP Server
- [](https://www.npmjs.com/package/@easecloudio/mcp-metabase-server)
- [](https://opensource.org/licenses/MIT)
- [](https://www.typescriptlang.org/)
- [](https://github.com/easecloudio/mcp-metabase-server)
- A **Model Context Protocol (MCP) server for Metabase** that gives AI assistants full access to your analytics platform — dashboards, cards, databases, tables, collections, and more.
- **Developed and maintained by [EaseCloud](https://easecloud.io)** — cloud-native, AI-driven, and data infrastructure solutions.
- ## Quick Start
- ```bash
- export METABASE_URL=https://your-metabase-instance.com
- export METABASE_API_KEY=your_metabase_api_key
- npx @easecloudio/mcp-metabase-server
- ```
- ## 96 Tools Available
- | Domain | Tools |
- |---|---|
- | Dashboard Management | 27 |
- | Card / Question Management | 21 |
- | Database Management | 16 |
- | Table Management | 17 |
- | Collections, Users & Search | 13 |
- | Schema Cache (SQL→MBQL) | 2 |
- ## Supported Metabase Versions
- - Metabase v0.46.x and above (recommended: v0.48.x or later)
- - Metabase Cloud (fully supported)
- - Self-hosted instances (Docker, JAR, or cloud deployments)
- ## Installation
- ### npx (Recommended)
- ```bash
- npx @easecloudio/mcp-metabase-server
- ```
- ### Global install
- ```bash
- npm install -g @easecloudio/mcp-metabase-server
- mcp-metabase-server
- ```
- ### Docker
- ```bash
- docker build -t mcp-metabase-server .
- docker run -it --rm \
- -e METABASE_URL=https://your-metabase-instance.com \
- -e METABASE_API_KEY=your_metabase_api_key \
- mcp-metabase-server
- ```
- ## Configuration
- ### Authentication
- **API Key (preferred):**
- ```bash
- METABASE_URL=https://your-metabase-instance.com
- METABASE_API_KEY=your_metabase_api_key
- ```
- **Username / Password (fallback):**
- ```bash
- METABASE_URL=https://your-metabase-instance.com
- METABASE_USERNAME=your_username
- METABASE_PASSWORD=your_password
- ```
- Copy `.env.example` to `.env` and fill in your values.
- ### Tool Filtering (TOOL_MODE)
- Set `TOOL_MODE` to control which tools are exposed to the AI. Useful for limiting surface area or preventing accidental writes.
- | Mode | Description |
- |---|---|
- | `all` | Every available tool (default) |
- | `essential` | Core read + execute tools only |
- | `read` | All non-destructive tools |
- | `write` | All tools including create / update / delete |
- ```bash
- TOOL_MODE=essential # smallest surface area
- TOOL_MODE=read # read-only
- TOOL_MODE=all # everything (default)
- ```
- ## Claude Desktop Integration
- MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%/Claude/claude_desktop_config.json`
- **Using npx:**
- ```json
- {
- "mcpServers": {
- "metabase": {
- "command": "npx",
- "args": ["@easecloudio/mcp-metabase-server"],
- "env": {
- "METABASE_URL": "https://your-metabase-instance.com",
- "METABASE_API_KEY": "your_metabase_api_key"
- }
- }
- }
- }
- ```
- **With tool filtering:**
- ```json
- {
- "mcpServers": {
- "metabase": {
- "command": "npx",
- "args": ["@easecloudio/mcp-metabase-server"],
- "env": {
- "METABASE_URL": "https://your-metabase-instance.com",
- "METABASE_API_KEY": "your_metabase_api_key",
- "TOOL_MODE": "essential"
- }
- }
- }
- }
- ```
- **Using a local build:**
- ```json
- {
- "mcpServers": {
- "metabase": {
- "command": "node",
- "args": ["/path/to/metabase-server/dist/index.js"],
- "env": {
- "METABASE_URL": "https://your-metabase-instance.com",
- "METABASE_API_KEY": "your_metabase_api_key"
- }
- }
- }
- }
- ```
- **Username / password fallback:**
- ```json
- {
- "mcpServers": {
- "metabase": {
- "command": "npx",
- "args": ["@easecloudio/mcp-metabase-server"],
- "env": {
- "METABASE_URL": "https://your-metabase-instance.com",
- "METABASE_USERNAME": "your_username",
- "METABASE_PASSWORD": "your_password"
- }
- }
- }
- }
- ```
- ## Available Tools
- <details>
- <summary><strong>Dashboard Management (27 tools)</strong></summary>
- ### Core CRUD
- | Tool | Description |
- |---|---|
- | `list_dashboards` | List all dashboards |
- | `get_dashboard` | Get a specific dashboard by ID |
- | `create_dashboard` | Create a new dashboard |
- | `update_dashboard` | Update an existing dashboard |
- | `delete_dashboard` | Delete / archive a dashboard |
- | `copy_dashboard` | Duplicate a dashboard (shallow or deep copy) |
- | `save_dashboard` | Save a complete dashboard object with nested data |
- | `save_dashboard_to_collection` | Move a dashboard into a specific collection |
- | `search_dashboards` | Search dashboards by name or description |
- | `favorite_dashboard` | Mark a dashboard as a favourite |
- | `unfavorite_dashboard` | Remove a dashboard from favourites |
- ### Card Layout
- | Tool | Description |
- |---|---|
- | `get_dashboard_cards` | Get all cards in a dashboard |
- | `add_card_to_dashboard` | Add a card with positioning |
- | `add_text_block` | Add a text or heading block to a dashboard |
- | `remove_card_from_dashboard` | Remove a card |
- | `update_dashboard_card` | Update card position, size, and settings |
- | `update_dashboard_cards` | Bulk-replace all cards on a dashboard |
- | `update_dashcard` | Update a specific dashcard's properties |
- | `execute_dashboard_card` | Execute a specific dashcard and return results |
- ### Public Sharing & Embedding
- | Tool | Description |
- |---|---|
- | `create_dashboard_public_link` | Create a public sharing link |
- | `delete_dashboard_public_link` | Remove the public link |
- | `list_public_dashboards` | List dashboards with public links |
- | `list_embeddable_dashboards` | List dashboards enabled for embedding |
- ### Revision, Audit & Discovery
- | Tool | Description |
- |---|---|
- | `get_dashboard_revisions` | Get revision history (audit trail) |
- | `revert_dashboard` | Revert to a previous revision |
- | `get_dashboard_related` | Get related content suggestions |
- | `get_dashboard_queries` | Extract all card queries with resolved field IDs |
- </details>
- <details>
- <summary><strong>Card / Question Management (21 tools)</strong></summary>
- ### Core CRUD
- | Tool | Description |
- |---|---|
- | `list_cards` | List all questions / cards |
- | `get_card` | Get a card by ID (includes full SQL / MBQL query) |
- | `create_card` | Create a new question |
- | `update_card` | Update an existing question |
- | `delete_card` | Delete / archive a question |
- | `copy_card` | Duplicate a card |
- | `move_cards` | Move one or more cards to a different collection |
- | `move_cards_to_collection` | Bulk-move cards from a source collection |
- ### Execution & Export
- | Tool | Description |
- |---|---|
- | `execute_card` | Run a card and return results |
- | `execute_pivot_card_query` | Run a card formatted as a pivot table |
- | `export_card_result` | Export results as CSV or JSON |
- ### Parameters
- | Tool | Description |
- |---|---|
- | `get_card_param_values` | Get available values for a card parameter |
- | `search_card_param_values` | Search / filter parameter values |
- | `get_card_param_remapping` | Get how parameter values are remapped for display |
- ### Metadata & Discovery
- | Tool | Description |
- |---|---|
- | `get_card_query_metadata` | Get column types and display names |
- | `get_card_dashboards` | List dashboards containing this card |
- | `get_card_series` | Get series data or related card suggestions |
- ### Public Sharing & Embedding
- | Tool | Description |
- |---|---|
- | `create_card_public_link` | Create a public sharing link |
- | `delete_card_public_link` | Remove the public link |
- | `list_public_cards` | List cards with public links |
- | `list_embeddable_cards` | List cards enabled for embedding |
- </details>
- <details>
- <summary><strong>Database Management (16 tools)</strong></summary>
- ### Core CRUD
- | Tool | Description |
- |---|---|
- | `list_databases` | List all database connections |
- | `get_database` | Get a specific database by ID |
- | `create_database_connection` | Create a new database connection |
- | `update_database` | Update a database connection's config or credentials |
- | `delete_database` | Permanently remove a database connection |
- | `add_sample_database` | Add the built-in H2 sample database with demo data |
- ### Querying
- | Tool | Description |
- |---|---|
- | `execute_query` | Execute a SQL query against a database |
- ### Schema & Sync
- | Tool | Description |
- |---|---|
- | `get_database_schema` | Get schema information |
- | `get_database_tables` | Get all tables in a database |
- | `get_database_metadata` | Get full metadata including all tables and field IDs |
- | `list_database_schemas` | List all schemas within a database |
- | `sync_database_schema` | Trigger a schema metadata sync |
- | `get_database_sync_status` | Check sync status |
- ### Diagnostics
- | Tool | Description |
- |---|---|
- | `check_database_health` | Check connection health |
- | `validate_database` | Validate connection settings before saving |
- | `test_database_connection` | Test an existing connection |
- </details>
- <details>
- <summary><strong>Table Management (17 tools)</strong></summary>
- ### Metadata
- | Tool | Description |
- |---|---|
- | `list_tables` | List tables (optionally filtered by database) |
- | `get_table` | Get table metadata by ID |
- | `get_table_metadata` | Get full query metadata including field IDs and types |
- | `get_table_fks` | Get foreign key relationships |
- | `get_table_related` | Find related tables via FK relationships |
- | `get_table_data` | Get a sample data preview from a table |
- | `get_field_id` | Look up a field ID by table ID + column name (returns MBQL ref) |
- ### Card Virtual Tables
- | Tool | Description |
- |---|---|
- | `get_card_table_fks` | Get FK relationships for a card's virtual table |
- | `get_card_table_query_metadata` | Get query metadata for a card's virtual table |
- ### Management
- | Tool | Description |
- |---|---|
- | `update_table` | Update display name, description, or visibility |
- | `update_tables` | Bulk-update multiple tables with the same config |
- | `reorder_table_fields` | Change the display order of fields |
- | `sync_table_schema` | Trigger a schema sync for a specific table |
- | `rescan_table_field_values` | Rescan field values (updates filter dropdowns) |
- | `discard_table_field_values` | Discard cached field values |
- ### CSV Upload (Metabase-managed tables)
- | Tool | Description |
- |---|---|
- | `append_csv_to_table` | Append new rows from CSV content |
- | `replace_table_csv` | Replace all table data with new CSV content |
- </details>
- <details>
- <summary><strong>Collections, Users & Search (13 tools)</strong></summary>
- ### Collections
- | Tool | Description |
- |---|---|
- | `list_collections` | List all collections |
- | `create_collection` | Create a new collection |
- | `get_collection` | Get collection details |
- | `update_collection` | Update name, description, color, or parent |
- | `delete_collection` | Delete a collection and its contents |
- | `get_collection_items` | List cards, dashboards, and sub-collections |
- | `move_to_collection` | Move a card or dashboard to a different collection |
- ### Users
- | Tool | Description |
- |---|---|
- | `list_users` | List all users |
- | `create_user` | Create a new user |
- ### Permissions
- | Tool | Description |
- |---|---|
- | `list_permission_groups` | List all permission groups |
- | `create_permission_group` | Create a new permission group |
- ### Search
- | Tool | Description |
- |---|---|
- | `search_content` | Search across all Metabase content |
- </details>
- <details>
- <summary><strong>Schema Cache — SQL to MBQL (2 tools)</strong></summary>
- These tools enable an AI to convert native SQL questions into interactive MBQL questions. Metabase has no REST API for this conversion — it requires field IDs, which these tools cache locally.
- **How it works:**
- 1. `get_card` — extract the SQL and `database_id`
- 2. `get_schema_cache` — get tables + field IDs for MBQL references like `["field", 42, null]`
- 3. AI translates SQL → MBQL using the cached field IDs
- 4. `create_card` — save the new interactive question
- Cache is stored at `~/.easecloud/metabase-mcp/cache/{url-hash}/` with a 24-hour TTL and scoped per Metabase instance.
- | Tool | Description |
- |---|---|
- | `get_schema_cache` | Return cached schema (auto-fetches if missing or stale) |
- | `refresh_schema_cache` | Force-refresh cache for one or all databases |
- </details>
- ## MCP Resources
- Access Metabase entities directly via `metabase://` URIs:
- | URI | Description |
- |---|---|
- | `metabase://dashboard/{id}` | Dashboard details |
- | `metabase://card/{id}` | Card / question details |
- | `metabase://database/{id}` | Database information |
- | `metabase://collection/{id}` | Collection details |
- | `metabase://user/{id}` | User information |
- | `metabase://table/{id}` | Table metadata |
- | `metabase://field/{id}` | Field information |
- ## Development
- ```bash
- npm install
- npm run build # compile TypeScript → dist/
- npm run watch # incremental rebuild
- npm run dev # build + start
- npm run inspector # launch MCP Inspector for debugging
- ```
- ## Debugging
- MCP servers communicate over stdio, which makes direct debugging awkward. Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
- ```bash
- npm run inspector
- ```
- The Inspector provides a browser UI for sending tool calls and inspecting responses.
- ## About EaseCloud
- EaseCloud is a cloud consulting and solutions company specializing in:
- - Cloud-native application development
- - AI & automation integrations
- - DevOps and infrastructure management
- - Data analytics and BI platform consulting
- We built this project to contribute to the open-source MCP ecosystem while demonstrating our expertise in integration, automation, and cloud solutions.
- If your team is adopting Metabase at scale or looking to integrate AI with your BI stack, [get in touch](https://easecloud.io) — we provide consulting, customization, and managed support for enterprises.
- 📧 [support@easecloud.io](mailto:support@easecloud.io)
- 🌐 [easecloud.io](https://easecloud.io)
- ## Bug Reports & Issues
- Found a bug or have a feature request?
- 🐛 [Create a GitHub issue](https://github.com/easecloudio/mcp-metabase-server/issues)
- Please include:
- - Metabase version
- - MCP server version
- - Steps to reproduce
- - Expected vs actual behavior
- - Any error messages or logs
- ## Contributing
- Contributions are welcome. Visit the [GitHub repository](https://github.com/easecloudio/mcp-metabase-server) to submit issues or pull requests.
- ## License
- MIT — see [LICENSE](LICENSE) for details.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.