<div align="center">

🚀 Metabase AI Assistant

The Most Powerful MCP Server for Metabase

134 Tools • MCP SDK v1.26.0 • AI-Powered SQL • Structured Output • Enterprise Security

Turn your AI assistant into a Metabase power user.
Generate SQL from natural language, create dashboards, manage users, and automate BI workflows.

📦 Install Now • 📖 Documentation • 🎯 Features • ⭐ Star Us

</div>

---

⭐ Why This Project?

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

| Feature | This Project | Other MCP Servers | |---------|:----------------:|:-----------------:| | Total Tools | 134 ✅ | 6-30 | | AI SQL Generation | ✅ | ❌ | | AI SQL Optimization | ✅ | ❌ | | Dashboard Templates | ✅ | ❌ | | User Management | ✅ | ❌ | | Workspace Export/Import | ✅ | ❌ | | Read-Only Security Mode | ✅ | ✅ | | Response Caching | ✅ | ✅ | | Activity Logging | ✅ | ❌ | | Metadata Analytics | ✅ | ❌ | | Parametric Questions | ✅ | ❌ | | Environment Comparison | ✅ | ❌ | | Structured Output (JSON) | ✅ | ❌ | | Tool Annotations | ✅ | ❌ |

---

🚀 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.

<details> <summary><b>📊 Database Operations (25 tools)</b></summary>

| Tool | Description | |------|-------------| | db_list | List all databases | | db_schemas | Get schemas in a database | | db_tables | Get tables with fields | | sql_execute | Execute SQL queries | | db_table_create | Create tables (AI-prefixed) | | db_view_create | Create views | | db_matview_create | Create materialized views | | db_index_create | Create indexes | | db_vacuum_analyze | VACUUM and ANALYZE | | db_query_explain | EXPLAIN query plans | | db_table_stats | Table statistics | | db_index_usage | Index usage analysis | | db_schema_explore | Fast schema exploration | | db_schema_analyze | Deep schema analysis | | db_relationships_detect | Detect foreign keys | | ...and more |

</details> <details> <summary><b>🤖 AI-Powered Features (5 tools)</b></summary>

| Tool | Description | |------|-------------| | ai_sql_generate | Natural language → SQL | | ai_sql_optimize | Query optimization suggestions | | ai_sql_explain | Explain SQL in plain English | | ai_relationships_suggest | Suggest table relationships | | mb_auto_describe | Auto-generate descriptions |

</details> <details> <summary><b>📋 Question/Card Management (12 tools)</b></summary>

| Tool | Description | |------|-------------| | mb_question_create | Create new questions | | mb_questions | List all questions | | mb_question_create_parametric | Parametric questions | | mb_card_get | Get card details | | mb_card_update | Update cards | | mb_card_delete | Delete cards | | mb_card_archive | Archive cards | | mb_card_data | Get card data as JSON | | mb_card_copy | Copy cards | | mb_card_clone | Clone cards | | ...and more |

</details> <details> <summary><b>📈 Dashboard Management (14 tools)</b></summary>

| Tool | Description | |------|-------------| | mb_dashboard_create | Create dashboards | | mb_dashboards | List all dashboards | | mb_dashboard_get | Get dashboard details | | mb_dashboard_update | Update dashboards | | mb_dashboard_delete | Delete dashboards | | mb_dashboard_add_card | Add cards to dashboard | | mb_dashboard_add_filter | Add filters | | mb_dashboard_layout_optimize | Optimize layout | | mb_dashboard_template_executive | Executive templates | | ...and more |

</details> <details> <summary><b>👥 User & Permission Management (10 tools)</b></summary>

| Tool | Description | |------|-------------| | mb_user_list | List users | | mb_user_get | Get user details | | mb_user_create | Create users | | mb_user_update | Update users | | mb_user_disable | Disable users | | mb_permission_group_list | List groups | | mb_permission_group_create | Create groups | | ...and more |

</details> <details> <summary><b>📊 Metadata Analytics (14 tools)</b></summary>

| Tool | Description | |------|-------------| | mb_meta_overview | Instance health check | | mb_meta_query_performance | Query analytics | | mb_meta_content_usage | Content usage stats | | mb_meta_user_activity | User activity | | mb_meta_table_dependencies | Table dependencies | | mb_meta_impact_analysis | Breaking change analysis | | mb_meta_optimization_recommendations | Index suggestions | | mb_meta_export_workspace | Backup to JSON | | mb_meta_import_preview | Import dry-run | | mb_meta_compare_environments | Dev vs Prod diff | | mb_meta_auto_cleanup | Safe cleanup | | ...and more |

</details>

---

🛡️ Security Features

| Feature | Description | |---------|-------------| | 🔒 Read-Only Mode | Blocks INSERT, UPDATE, DELETE, DROP (default: enabled) | | 🏷️ AI Prefix | All AI-created objects use claude_ai_ prefix | | ✅ Explicit Approval | Destructive operations require confirmation | | 📝 Activity Logging | Full audit trail of all operations | | 🔐 Env Validation | Zod-validated environment variables | | 💾 Auto-Backup | Prompts for backup before destructive ops |

# 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
# METABASE_USERNAME=admin@example.com
# 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

---

<div align="center">

⭐ Star this repo if it helps you!

Built with ❤️ by Abdullah Enes SARI @ ONMARTECH LLC

---

Keywords: Metabase MCP Server, Model Context Protocol, AI SQL Generation, Business Intelligence, Claude AI, Cursor AI, Natural Language SQL, Dashboard Automation, PostgreSQL, Data Analytics, LLM Tools

</div>