Metabase MCP 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.

Fork of @easecloudio/mcp-metabase-server, maintained by Azhar Sirajuddin. Fixes list_tables/get_database_tables, which 404 on current Metabase versions because upstream still calls the removed GET /api/database/{id}/tables route instead of GET /api/database/{id}?include=tables.

Quick Start

export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key
npx @imazhar101/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)

npx @imazhar101/mcp-metabase-server

Global install

npm install -g @imazhar101/mcp-metabase-server
mcp-metabase-server

Docker

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):

METABASE_URL=https://your-metabase-instance.com
METABASE_API_KEY=your_metabase_api_key

Username / Password (fallback):

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 |

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:

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@imazhar101/mcp-metabase-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

With tool filtering:

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@imazhar101/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:

{
  "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:

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@imazhar101/mcp-metabase-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_USERNAME": "your_username",
        "METABASE_PASSWORD": "your_password"
      }
    }
  }
}

Available Tools

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 |

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 |

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 |

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 |

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 |

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 ~/.mcp-metabase-server/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 |

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

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:

npm run inspector

The Inspector provides a browser UI for sending tool calls and inspecting responses.

Credits

Originally built by EaseCloud; this fork is independently maintained by Azhar Sirajuddin and is not affiliated with or supported by EaseCloud. For issues or support, use this repo's issue tracker.

Bug Reports & Issues

Found a bug or have a feature request?

🐛 Create a GitHub issue

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 to submit issues or pull requests.

License

MIT — see LICENSE for details.