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

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

🧪 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