Readme: Metabase MCP Server

A comprehensive Model Context Protocol (MCP) server for Metabase integration, providing AI assistants with full access to Metabase's analytics platform.

🚀 Quick Start

# Install and run with npx
export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key
npx @cognitionai/metabase-mcp-server

✨ Features

🎯 81+ Tools Available - Complete Metabase API Coverage

• 📊 Dashboard Management (23 tools) - Full CRUD operations, card management, public sharing, embedding

• 📈 Card/Question Management (21 tools) - Query execution, parameter handling, pivot queries, public links

• 🗄️ Database Management (13 tools) - Connection management, schema sync, query execution

• 📋 Table Management (16 tools) - Metadata operations, field management, data operations

• 🔍 Additional Tools (9 tools) - Collections, search, users, activity tracking, playground links

📦 Installation

💡 Recommended: Node.js 20.19.0+ and npm 8.0.0+ for optimal compatibility

Method 1: NPX (Recommended)

npx @cognitionai/metabase-mcp-server

Method 2: Global Installation

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

Method 3: Docker

docker run -it --rm \
  -e METABASE_URL=https://your-metabase-instance.com \
  -e METABASE_API_KEY=your_metabase_api_key \
  ghcr.io/CognitionAI/metabase-mcp-server

⚙️ Configuration

Environment Variables

API Key Authentication (Preferred):

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

Username/Password Authentication (Fallback):

export METABASE_URL=https://your-metabase-instance.com
export METABASE_USERNAME=your_username
export METABASE_PASSWORD=your_password

Extra Request Headers (Optional):

Use METABASE_HEADER_<NAME> to inject additional headers into every outgoing request — useful for reverse proxies, API gateways, or multi-tenant setups that require extra auth tokens or routing headers.

The suffix is converted to a header name by replacing _ with -:

# Adds "Authorization: Bearer <token>" to every request
export METABASE_HEADER_AUTHORIZATION="Bearer your-token"

# Adds "X-Tenant-Id: my-org"
export METABASE_HEADER_X_TENANT_ID="my-org"

# Adds "X-Api-Gateway-Key: secret"
export METABASE_HEADER_X_API_GATEWAY_KEY="secret"

Optional Arguments

The server supports command-line arguments to customize tool loading:

• --essential (default): Load only essential tools

• --all: Load all 80+ available tools

• --write: Load only write/modification tools

• --read: Load only read-only tools

# Using published package (recommended)
# Default behavior (essential tools only)
npx @cognitionai/metabase-mcp-server

# Load all tools
npx @cognitionai/metabase-mcp-server --all

# Load only write tools
npx @cognitionai/metabase-mcp-server --write

# Load only read-only tools
npx @cognitionai/metabase-mcp-server --read

# Using local development build
npm run build
node dist/server.js                    # Default (essential tools)
node dist/server.js --all             # All tools
node dist/server.js --write           # Write tools only
node dist/server.js --read            # Read-only tools only

🔌 Integration Examples

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Using published package:

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

Using local development build:

{
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/path/to/metabase-mcp-server/dist/server.js"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

With custom flags:

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

With extra headers (e.g. behind a reverse proxy or API gateway):

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key",
        "METABASE_HEADER_AUTHORIZATION": "Bearer your-proxy-token",
        "METABASE_HEADER_X_TENANT_ID": "my-org"
      }
    }
  }
}

Windsurf IDE

Add to your Windsurf MCP config (~/.windsurf/mcp_config.json):

Using published package:

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

Using local development build:

{
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/path/to/metabase-mcp-server/dist/server.js"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

With custom flags:

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

🛠️ Available Tools

Core Operations

• list_dashboards - List all dashboards

• get_dashboard - Get dashboard by ID

• create_dashboard - Create new dashboard

• update_dashboard - Update existing dashboard

• delete_dashboard - Delete dashboard

• copy_dashboard - Copy dashboard

Card Management

• get_dashboard_cards - Get all cards in dashboard

• add_card_to_dashboard - Add card to dashboard

• remove_card_from_dashboard - Remove card from dashboard

• update_dashboard_card - Update card position/settings

• execute_dashboard_card - Execute specific dashboard card

Public Sharing & Embedding

• create_public_link - Create public dashboard link

• delete_public_link - Delete public dashboard link

• list_public_dashboards - List public dashboards

• list_embeddable_dashboards - List embeddable dashboards

Parameters & Queries

• get_dashboard_param_values - Get parameter values

• search_dashboard_param_values - Search parameter values

• get_dashboard_param_remapping - Get parameter remapping

• execute_dashboard_query - Execute dashboard queries

Advanced Features

• get_dashboard_related - Get related content

• get_dashboard_query_metadata - Get query metadata

• update_dashboard_cards - Bulk update cards

• save_dashboard - Save dashboard changes

• get_dashboard_items - Get dashboard items

Core Operations

• list_cards - List all cards/questions

• get_card - Get card by ID

• create_card - Create new card

• update_card - Update existing card

• delete_card - Delete card

• copy_card - Copy card

Query Execution

• execute_card - Execute card query

• execute_card_query_with_format - Execute with specific format

• execute_pivot_card_query - Execute pivot query

• get_card_query_metadata - Get query metadata

Card Management

• move_cards - Move cards between collections

• move_cards_to_collection - Bulk move to collection

• get_card_dashboards - Get dashboards containing card

• get_card_series - Get card series data

Parameters & Values

• get_card_param_values - Get parameter values

• search_card_param_values - Search parameter values

• get_card_param_remapping - Get parameter remapping

Public Sharing

• create_card_public_link - Create public card link

• delete_card_public_link - Delete public card link

• get_public_cards - List public cards

• get_embeddable_cards - List embeddable cards

Core Operations

• list_databases - List all databases

• get_database - Get database details

• create_database - Create database connection

• update_database - Update database settings

• delete_database - Delete database connection

Schema & Metadata

• get_database_schema_tables - Get database tables

• get_database_schemas - Get database schemas

• get_database_metadata - Get complete metadata

• sync_database_schema - Sync schema metadata

Query Operations

• execute_query - Execute SQL queries

• execute_query_export - Execute and export results

Maintenance

• get_database_usage_info - Get usage statistics

• rescan_database_field_values - Rescan field values

Core Operations

• list_tables - List tables with filtering

• get_table - Get table details

• update_table - Update table configuration

• update_tables - Bulk update tables

Data Operations

• get_table_data - Retrieve table data

• append_csv_to_table - Append CSV data

• replace_table_csv - Replace with CSV data

Schema & Relationships

• get_table_query_metadata - Get query metadata

• get_table_fks - Get foreign key relationships

• get_table_related - Get related tables

• sync_table_schema - Sync table schema

Field Management

• reorder_table_fields - Reorder field display

• rescan_table_field_values - Rescan field values

• discard_table_field_values - Discard cached values

Card Integration

• get_card_table_fks - Get card table foreign keys

• get_card_table_query_metadata - Get card table metadata

Collections

• list_collections - List all collections

• create_collection - Create new collection

• update_collection - Update collection

• delete_collection - Delete collection

• get_collection_items - Get collection items

Search & Discovery

• search_content - Search across all content

Activity & Analytics

• get_recent_views - Get recent activity

• get_popular_items - Get popular content

Playground Links

• get_metabase_playground_link - Generate interactive playground links

🧪 Development

Setup

git clone https://github.com/CognitionAI/metabase-mcp-server.git
cd metabase-mcp-server
npm install

Build

npm run build

Development Mode

npm run watch

Debugging

Use the MCP Inspector for debugging:

npm run inspector

🔍 Testing Authentication

API Key Authentication

1. Set METABASE_URL and METABASE_API_KEY

2. Start server and verify "Using Metabase API Key" in logs

3. Test with list_dashboards tool

Username/Password Authentication

1. Unset METABASE_API_KEY

2. Set METABASE_URL, METABASE_USERNAME, METABASE_PASSWORD

3. Start server and verify "Using username/password" in logs

4. Test with list_dashboards tool

🐛 Troubleshooting

Common Issues

Authentication Errors:

• Verify your Metabase URL is accessible

• Check API key validity in Metabase admin settings

• Ensure username/password credentials are correct

Connection Issues:

• Confirm Metabase instance is running

• Check network connectivity

• Verify SSL certificates if using HTTPS

Tool Execution Errors:

• Check Metabase permissions for your user/API key

• Verify the requested resource exists

• Review server logs for detailed error messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please visit our GitHub repository to:

• 🐛 Report bugs

• 💡 Request features

• 🔧 Submit pull requests

• 📖 Improve documentation

Development Guidelines

1. Fork the repository

2. Create a feature branch

3. Make your changes with tests

4. Ensure all tests pass

5. Submit a pull request

🆘 Support

• 📚 Documentation

• 🐛 Issue Tracker

Built with ❤️ for the world