Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@cognitionai/metabase-mcp-server) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

🔗 MCP Resources

Access Metabase entities via standardized URIs:

metabase://dashboards - All dashboards
metabase://cards - All cards/questions
metabase://databases - All database connections
metabase://collections - All collections
metabase://users - All users

📦 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

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"
      }
    }
  }
}

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

📊 Dashboard Management (23 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

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

📈 Card/Question Management (21 tools)

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

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

🗄️ Database Management (13 tools)

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

📋 Table Management (16 tools)

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

🔍 Additional Tools (9 tools)

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

Set METABASE_URL and METABASE_API_KEY
Start server and verify "Using Metabase API Key" in logs
Test with list_dashboards tool

Username/Password Authentication

Unset METABASE_API_KEY
Set METABASE_URL, METABASE_USERNAME, METABASE_PASSWORD
Start server and verify "Using username/password" in logs
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

Fork the repository
Create a feature branch
Make your changes with tests
Ensure all tests pass
Submit a pull request

🆘 Support

📚 Documentation
🐛 Issue Tracker

Built with ❤️ for the world

@cognitionai/metabase-mcp-server

Package Exports

Readme

Readme: Metabase MCP Server

🚀 Quick Start

✨ Features

🎯 81+ Tools Available - Complete Metabase API Coverage

🔗 MCP Resources

📦 Installation

Method 1: NPX (Recommended)

Method 2: Global Installation

Method 3: Docker

⚙️ Configuration

Environment Variables

Optional Arguments

🔌 Integration Examples

Claude Desktop

Windsurf IDE

🛠️ Available Tools

Core Operations

Card Management

Public Sharing & Embedding

Parameters & Queries

Advanced Features

Core Operations

Query Execution

Card Management

Parameters & Values

Public Sharing

Core Operations

Schema & Metadata

Query Operations

Maintenance

Core Operations

Data Operations

Schema & Relationships

Field Management

Card Integration

Collections

Search & Discovery

Activity & Analytics

Playground Links

🧪 Development

Setup

Build

Development Mode

Debugging

🔍 Testing Authentication

API Key Authentication

Username/Password Authentication

🐛 Troubleshooting

Common Issues

📄 License

🤝 Contributing

Development Guidelines

🆘 Support