⭐ Why This Project?

"I analyzed every Metabase MCP server on the market. This one has 4x more tools and features than any competitor."

🚀 Quick Start

One-Line Install

npx metabase-ai-assistant

Add to Claude Desktop / Cursor

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["-y", "metabase-ai-assistant"],
      "env": {
        "METABASE_URL": "https://your-metabase.com",
        "METABASE_API_KEY": "mb_your_api_key"
      }
    }
  }
}

That's it! Your AI assistant now has full Metabase superpowers. 🦸

🎯 What Can You Do?

💬 Natural Language → SQL

You: "Show me total revenue by product category for the last 30 days"
AI: Uses ai_sql_generate → Runs query → Returns formatted results

📊 Instant Dashboard Creation

You: "Create an executive dashboard for our e-commerce sales"
AI: Uses mb_dashboard_template_executive → Creates fully configured dashboard

🔍 Deep Database Exploration

You: "What tables are related to 'orders' and show their relationships"
AI: Uses db_relationships_detect → Returns complete ER diagram info

🛡️ Enterprise-Grade Security

You: "DROP TABLE users" 
AI: 🔒 Blocked - Read-only mode active

🔧 Complete Tool List (134)

🆕 All tools include MCP annotations and title. 16 priority tools support outputSchema + structuredContent for typed JSON responses.

🛡️ Security Features

# Enable/disable read-only mode
METABASE_READ_ONLY_MODE=true  # Default: blocks write ops
METABASE_READ_ONLY_MODE=false # Allow write operations

⚙️ Configuration

Create a .env file:

# Required
METABASE_URL=https://your-metabase.com
METABASE_API_KEY=mb_your_api_key

# Or use username/password
# [email protected]
# METABASE_PASSWORD=your_password

# Security (defaults to true)
METABASE_READ_ONLY_MODE=true

# AI Features (optional)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

# Performance (optional)
CACHE_TTL_MS=600000  # 10 minutes

📦 Installation Options

npm (Recommended)

npm install -g metabase-ai-assistant

Docker

docker run -e METABASE_URL=... -e METABASE_API_KEY=... ghcr.io/enessari/metabase-ai-assistant

From Source

git clone https://github.com/enessari/metabase-ai-assistant.git
cd metabase-ai-assistant
npm install
npm run mcp

🏗️ Architecture

metabase-ai-assistant/
├── src/
│   ├── mcp/
│   │   ├── server.js              # MCP Server entry point
│   │   ├── tool-registry.js       # 134 tool definitions + annotations + outputSchema
│   │   ├── tool-router.js         # Dynamic routing with read-only gate
│   │   └── handlers/              # 15 modular handler files
│   ├── utils/
│   │   ├── structured-response.js # Structured output (MCP 2025-06-18)
│   │   ├── cache.js               # TTL-based caching
│   │   ├── config.js              # Zod validation
│   │   └── response-optimizer.js  # Compact response formatting
│   └── metabase/
│       └── client.js              # Metabase API client

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Fork, clone, install
git clone https://github.com/YOUR_USERNAME/metabase-ai-assistant.git
npm install

# Create feature branch
git checkout -b feature/amazing-feature

# Test and submit PR
npm test
git push origin feature/amazing-feature

📚 Resources

• 📖 Full Documentation
• 🐛 Report Issues
• 💬 Discussions
• 📦 npm Package

📄 License

Apache License 2.0 - see LICENSE