io.github.enessari/metabase-ai-assistant

Official

by enessari · JavaScript

MCP Server for Metabase - 111 tools for SQL generation, dashboards & PostgreSQL

Generate SQL queries and manage Metabase dashboards with PostgreSQL integration.

Topics

aiassistantmetabasereportingmetabase-mcpbusiness-intelligenceclaudecursorllmmcpmcp-servernatural-language-sqlsql

README.md11 KBView on GitHub

🚀 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

bash

npx metabase-ai-assistant

Add to Claude Desktop / Cursor

json

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

code

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

code

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

🔍 Deep Database Exploration

code

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

🛡️ Enterprise-Grade Security

code

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

bash

# 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:

bash

# 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)

bash

npm install -g metabase-ai-assistant

Docker

bash

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

From Source

bash

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

🏗️ Architecture

code

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.

bash

# 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

📄 License

Apache License 2.0 - see LICENSE

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

Install

Configuration

Environment variables

METABASE_URLrequired

Metabase instance URL (e.g., http://localhost:3000)

METABASE_USERNAME

Metabase username for authentication

METABASE_PASSWORDsecret

Metabase password for authentication

METABASE_API_KEYsecret

Metabase API key (alternative to username/password)

DATABASE_HOST

PostgreSQL database host for direct SQL execution

DATABASE_PORT

PostgreSQL database port

DATABASE_NAME

PostgreSQL database name

DATABASE_USER

PostgreSQL database user

DATABASE_PASSWORDsecret

PostgreSQL database password

claude_desktop_config.json

{
  "mcpServers": {
    "metabase-ai-assistant": {
      "command": "npx",
      "args": [
        "-y",
        "metabase-ai-assistant@3.2.0"
      ],
      "env": {
        "METABASE_URL": "<YOUR_METABASE_URL>",
        "METABASE_USERNAME": "<YOUR_METABASE_USERNAME>",
        "METABASE_PASSWORD": "<YOUR_METABASE_PASSWORD>",
        "METABASE_API_KEY": "<YOUR_METABASE_API_KEY>",
        "DATABASE_HOST": "<YOUR_DATABASE_HOST>",
        "DATABASE_PORT": "<YOUR_DATABASE_PORT>",
        "DATABASE_NAME": "<YOUR_DATABASE_NAME>",
        "DATABASE_USER": "<YOUR_DATABASE_USER>",
        "DATABASE_PASSWORD": "<YOUR_DATABASE_PASSWORD>"
      }
    }
  }
}