mcp-metabase-server P

# Metabase MCP Server [](https://opensource.org/licenses/MIT) [](https://github.com/easecloudio/mcp-metabase-server) A comprehensive **Model Context Protocol (MCP) server for Metabase integration**, designed for enterprises and developers who want to supercharge their AI assistants with live analytics and business intelligence. **Developed and maintained by [EaseCloud Technologies](https://easecloud.io)** — your trusted partner for **cloud-native, AI-driven, and data infrastructure solutions.** This is a TypeScript-based MCP server that implements full integration with Metabase API. It allows AI assistants to interact with Metabase, providing comprehensive access to: - **Complete CRUD Operations**: Full lifecycle management for all Metabase entities - **Advanced Dashboard Management**: Card positioning, parameters, subscriptions, and alerts - **User & Permission Management**: Complete user lifecycle and permission system control - **Database Management**: Connection management, schema sync, and metadata exploration - **Analytics & Monitoring**: Usage statistics, activity tracking, and system health monitoring - **Advanced Query Features**: Export, bookmarking, public sharing, and complex query execution - **Search & Discovery**: Global search, popular items, and content recommendations - **Settings & Configuration**: System settings and instance configuration management ## **70+ Tools Available** covering all major Metabase functionality for enterprise usage. ## Supported Metabase Versions This MCP server is compatible with: - **Metabase v0.46.x and above** (recommended: v0.48.x or later) - **Metabase Cloud** (fully supported) - **Self-hosted Metabase instances** (Docker, JAR, or cloud deployments) **Note:** Some advanced features may require newer Metabase versions. For optimal compatibility, we recommend using Metabase v0.48.0 or later. ## Why We Built This At EaseCloud, we help companies modernize their data platforms and unlock the power of AI. Metabase is a leading open-source BI tool — but connecting it with AI assistants like Claude, Cursor, and Windsurf requires complex API work. This MCP server removes that barrier by providing **70+ ready-to-use tools** that cover everything from dashboards to queries, permissions to monitoring. Our goal is to make **enterprise analytics accessible in natural language** while showcasing our expertise in **integration, automation, and cloud solutions.** ## Features ### Resources - Access Metabase resources via `metabase://` URIs - **Dashboards**: `metabase://dashboard/{id}` - Access dashboard details - **Cards/Questions**: `metabase://card/{id}` - Access question/card details - **Databases**: `metabase://database/{id}` - Access database information - **Collections**: `metabase://collection/{id}` - Access collection details - **Users**: `metabase://user/{id}` - Access user information - **Tables**: `metabase://table/{id}` - Access table metadata - **Fields**: `metabase://field/{id}` - Access field information - JSON content type for structured data access ### Core Data Management Tools #### Dashboard Management - `list_dashboards` - List all dashboards in Metabase - `create_dashboard` - Create a new dashboard - `update_dashboard` - Update an existing dashboard - `delete_dashboard` - Delete/archive a dashboard - `get_dashboard_cards` - Get all cards in a dashboard #### Card/Question Management - `list_cards` - List all questions/cards in Metabase - `create_card` - Create a new question/card - `update_card` - Update an existing question/card - `delete_card` - Delete/archive a question/card - `execute_card` - Execute a card and get results #### Database Operations - `list_databases` - List all databases in Metabase - `execute_query` - Execute a SQL query against a database ### Collections Management - `list_collections` - List all collections - `create_collection` - Create a new collection - `update_collection` - Update an existing collection - `delete_collection` - Delete a collection - `get_collection_items` - Get all items in a collection - `move_to_collection` - Move items between collections ### User & Permission Management - `list_users` - List all users - `create_user` - Create a new user - `update_user` - Update user details - `delete_user` - Deactivate a user - `list_permissions` - List permission groups and permissions - `list_permission_groups` - List all permission groups - `create_permission_group` - Create a new permission group - `update_permission_group` - Update a permission group - `delete_permission_group` - Delete a permission group - `add_user_to_group` - Add user to permission group - `remove_user_from_group` - Remove user from permission group ### Advanced Query Features - `export_card_results` - Export card results to CSV/JSON/Excel - `export_dashboard_data` - Export dashboard data to various formats - `bookmark_card` - Bookmark a card - `unbookmark_card` - Remove card bookmark - `bookmark_dashboard` - Bookmark a dashboard - `unbookmark_dashboard` - Remove dashboard bookmark - `list_bookmarked_items` - List all bookmarked items - `create_public_link` - Create public sharing link - `disable_public_link` - Disable public sharing - `get_public_link` - Get public link information ### Database Schema Operations - `get_database_schema` - Get database schema information - `get_database_tables` - Get all tables in a database - `get_table_metadata` - Get table metadata - `get_table_fields` - Get all fields in a table - `get_field_values` - Get field values - `get_field_summary` - Get field summary statistics - `analyze_field_values` - Analyze field values ### Search & Discovery - `search_content` - Search across all Metabase content - `get_recent_items` - Get recently viewed items - `get_popular_items` - Get most popular cards and dashboards ### Advanced Dashboard Features - `add_card_to_dashboard` - Add a card to a dashboard with positioning - `remove_card_from_dashboard` - Remove a card from a dashboard - `update_dashboard_card` - Update card position, size, and settings - `get_dashboard_parameters` - Get dashboard parameters - `update_dashboard_parameters` - Update dashboard parameters - `create_dashboard_subscription` - Create dashboard subscriptions/alerts - `list_dashboard_subscriptions` - List all dashboard subscriptions - `update_dashboard_subscription` - Update subscription settings - `delete_dashboard_subscription` - Delete a dashboard subscription ### Analytics & Monitoring - `get_user_activity` - Get user activity and usage statistics - `get_content_usage` - Get usage statistics for cards and dashboards - `get_system_usage_stats` - Get system-wide usage statistics - `get_system_health` - Get system health status ### Database Connection Management - `create_database_connection` - Create new database connections - `test_database_connection` - Test database connectivity - `sync_database_schema` - Sync database schema metadata - `get_database_sync_status` - Get database schema sync status ### Settings & Configuration - `get_metabase_settings` - Get Metabase instance settings - `update_metabase_settings` - Update instance settings ## Configuration Before running the server, you need to set environment variables for authentication. The server supports two methods: 1. **API Key (Preferred):** - `METABASE_URL`: The URL of your Metabase instance (e.g., `https://your-metabase-instance.com`). - `METABASE_API_KEY`: Your Metabase API key. 2. **Username/Password (Fallback):** - `METABASE_URL`: The URL of your Metabase instance. - `METABASE_USERNAME`: Your Metabase username. - `METABASE_PASSWORD`: Your Metabase password. The server will first check for `METABASE_API_KEY`. If it's set, API key authentication will be used. If `METABASE_API_KEY` is not set, the server will fall back to using `METABASE_USERNAME` and `METABASE_PASSWORD`. You must provide credentials for at least one of these methods. **Example setup:** Using API Key: ```bash # Required environment variables export METABASE_URL=https://your-metabase-instance.com export METABASE_API_KEY=your_metabase_api_key ``` Or, using Username/Password: ```bash # Required environment variables export METABASE_URL=https://your-metabase-instance.com export METABASE_USERNAME=your_username export METABASE_PASSWORD=your_password ``` You can set these environment variables in your shell profile or use a `.env` file with a package like `dotenv`. ## Development Install dependencies: ```bash npm install ``` Build the server: ```bash npm run build ``` For development with auto-rebuild: ```bash npm run watch ``` ## Installation & Usage ### Method 1: Using npx (Recommended) The easiest way to run the server is using npx: ```bash # Set environment variables export METABASE_URL=https://your-metabase-instance.com export METABASE_API_KEY=your_metabase_api_key # Run the server npx @easecloudio/mcp-metabase-server ``` ### Method 2: Using Node.js directly If you have the package installed locally or globally: ```bash # Install globally npm install -g @easecloudio/mcp-metabase-server # Set environment variables export METABASE_URL=https://your-metabase-instance.com export METABASE_API_KEY=your_metabase_api_key # Run the server mcp-metabase-server ``` Or run from the built project: ```bash # Clone and build the project git clone https://github.com/easecloudio/mcp-metabase-server.git cd mcp-metabase-server npm install npm run build # Set environment variables export METABASE_URL=https://your-metabase-instance.com export METABASE_API_KEY=your_metabase_api_key # Run the server node dist/index.js ``` ### Method 3: Using Docker You can run the server using Docker: ```bash # Build the Docker image docker build -t mcp-metabase-server . # Run the container docker run -it --rm \ -e METABASE_URL=https://your-metabase-instance.com \ -e METABASE_API_KEY=your_metabase_api_key \ mcp-metabase-server ``` Or using docker-compose: ```yaml # docker-compose.yml version: "3.8" services: mcp-metabase-server: build: . environment: - METABASE_URL=https://your-metabase-instance.com - METABASE_API_KEY=your_metabase_api_key stdin_open: true tty: true ``` Then run: ```bash docker-compose up ``` ### Integration with Claude Desktop To use with Claude Desktop, add the server config: On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json` On Windows: `%APPDATA%/Claude/claude_desktop_config.json` #### Using npx: ```json { "mcpServers": { "metabase-server": { "command": "npx", "args": ["@easecloudio/mcp-metabase-server"], "env": { "METABASE_URL": "https://your-metabase-instance.com", "METABASE_API_KEY": "your_metabase_api_key" } } } } ``` #### Using Node.js directly: ```json { "mcpServers": { "metabase-server": { "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" } } } } ``` #### Alternative authentication (username/password): ```json { "mcpServers": { "metabase-server": { "command": "npx", "args": ["@easecloudio/mcp-metabase-server"], "env": { "METABASE_URL": "https://your-metabase-instance.com", "METABASE_USERNAME": "your_username", "METABASE_PASSWORD": "your_password" } } } } ``` ### Environment Variables The server supports the following environment variables: - **METABASE_URL** (required): The URL of your Metabase instance - **METABASE_API_KEY** (preferred): Your Metabase API key - **METABASE_USERNAME**: Your Metabase username (fallback if API key not provided) - **METABASE_PASSWORD**: Your Metabase password (fallback if API key not provided) ### Debugging Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script: ```bash npm run inspector ``` The Inspector will provide a URL to access debugging tools in your browser. ## Testing After configuring the environment variables as described in the "Configuration" section, you can manually test the server's authentication. The MCP Inspector (`npm run inspector`) is a useful tool for sending requests to the server. ### 1. Testing with API Key Authentication 1. Set the `METABASE_URL` and `METABASE_API_KEY` environment variables with your Metabase instance URL and a valid API key. 2. Ensure `METABASE_USERNAME` and `METABASE_PASSWORD` are unset or leave them, as the API key should take precedence. 3. Start the server: `npm run build && node build/index.js` (or use your chosen method for running the server, like via Claude Desktop config). 4. Check the server logs. You should see a message indicating that it's using API key authentication (e.g., "Using Metabase API Key for authentication."). 5. Using an MCP client or the MCP Inspector, try calling a tool, for example, `tools/call` with `{"name": "list_dashboards"}`. 6. Verify that the tool call is successful and you receive the expected data. ### 2. Testing with Username/Password Authentication (Fallback) 1. Ensure the `METABASE_API_KEY` environment variable is unset. 2. Set `METABASE_URL`, `METABASE_USERNAME`, and `METABASE_PASSWORD` with valid credentials for your Metabase instance. 3. Start the server. 4. Check the server logs. You should see a message indicating that it's using username/password authentication (e.g., "Using Metabase username/password for authentication." followed by "Authenticating with Metabase using username/password..."). 5. Using an MCP client or the MCP Inspector, try calling the `list_dashboards` tool. 6. Verify that the tool call is successful. ### 3. Testing Authentication Failures - **Invalid API Key:** 1. Set `METABASE_URL` and an invalid `METABASE_API_KEY`. Ensure `METABASE_USERNAME` and `METABASE_PASSWORD` variables are unset. 2. Start the server. 3. Attempt to call a tool (e.g., `list_dashboards`). The tool call should fail, and the server logs might indicate an authentication error from Metabase (e.g., "Metabase API error: Invalid X-API-Key"). - **Invalid Username/Password:** 1. Ensure `METABASE_API_KEY` is unset. Set `METABASE_URL` and invalid `METABASE_USERNAME`/`METABASE_PASSWORD`. 2. Start the server. 3. Attempt to call a tool. The tool call should fail due to failed session authentication. The server logs might show "Authentication failed" or "Failed to authenticate with Metabase". - **Missing Credentials:** 1. Unset `METABASE_API_KEY`, `METABASE_USERNAME`, and `METABASE_PASSWORD`. Set only `METABASE_URL`. 2. Attempt to start the server. 3. The server should fail to start and log an error message stating that authentication credentials (either API key or username/password) are required (e.g., "Either (METABASE_URL and METABASE_API_KEY) or (METABASE_URL, METABASE_USERNAME, and METABASE_PASSWORD) environment variables are required"). ## About EaseCloud Technologies 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 deep expertise in **data-driven decision systems.** 👉 If your team is adopting Metabase at scale or looking to integrate AI with your BI stack, [get in touch with us](https://easecloud.io) — we provide **consulting, customization, and managed support** for enterprises. --- 💡 **Work with EaseCloud** Need help deploying, customizing, or scaling Metabase in production? We provide end-to-end support for BI, AI, and cloud infrastructure. 📧 Contact us: [support@easecloud.io](mailto:support@easecloud.io) 🌐 Learn more: [https://easecloud.io](https://easecloud.io) --- ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Support For support, please contact us at [support@easecloud.io](mailto:support@easecloud.io) or visit our website at [EaseCloud.io](https://easecloud.io). ## Bug Reports & Issues Found a bug or have a feature request? We'd love to hear from you! 🐛 **Report Issues**: [Create a bug report on GitHub](https://github.com/easecloudio/mcp-metabase-server/issues) When reporting issues, please include: - Metabase version you're using - MCP server version - Steps to reproduce the issue - Expected vs actual behavior - Any error messages or logs ## Contributing Contributions are welcome! Please visit our [GitHub repository](https://github.com/easecloudio/mcp-metabase-server) to submit issues or pull requests.