---

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

📊 Database Operations (25 tools)

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

🤖 AI-Powered Features (5 tools)

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

📋 Question/Card Management (12 tools)

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

📈 Dashboard Management (14 tools)

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

👥 User & Permission Management (10 tools)

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

📊 Metadata Analytics (14 tools)

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

---

🛡️ 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

---