# Metabase Ai Assistant

> 🚀 The most powerful MCP Server for Metabase - 111+ tools for AI SQL generation, dashboard automation & enterprise BI. Works with Claude, Cursor, ChatGPT.

- **Type:** MCP server
- **Install:** `agentstack add mcp-enessari-metabase-ai-assistant`
- **Verified:** Pending review
- **Seller:** [enessari](https://agentstack.voostack.com/s/enessari)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [enessari](https://github.com/enessari)
- **Source:** https://github.com/enessari/metabase-ai-assistant

## Install

```sh
agentstack add mcp-enessari-metabase-ai-assistant
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🚀 Metabase AI Assistant

### **The Most Powerful MCP Server for Metabase**

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

[](https://www.npmjs.com/package/metabase-ai-assistant)
[](https://www.npmjs.com/package/metabase-ai-assistant)
[](https://github.com/enessari/metabase-ai-assistant/stargazers)
[](https://opensource.org/licenses/Apache-2.0)

[](https://modelcontextprotocol.io/)
[](https://claude.ai)
[](https://cursor.sh)
[](https://nodejs.org/)
[](https://lobehub.com/mcp/onmartech-metabase-ai-assistant)
---

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

[**📦 Install Now**](#-quick-start) • [**📖 Documentation**](#-available-tools) • [**🎯 Features**](#-why-this-project) • [**⭐ Star Us**](https://github.com/enessari/metabase-ai-assistant)

---

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

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

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

```
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](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

- [📖 Full Documentation](https://github.com/enessari/metabase-ai-assistant/wiki)
- [🐛 Report Issues](https://github.com/enessari/metabase-ai-assistant/issues)
- [💬 Discussions](https://github.com/enessari/metabase-ai-assistant/discussions)
- [📦 npm Package](https://www.npmjs.com/package/metabase-ai-assistant)

---

## 📄 License

Apache License 2.0 - see [LICENSE](LICENSE)

---

### ⭐ Star this repo if it helps you!

**Built with ❤️ by [Abdullah Enes SARI](https://github.com/enessari) @ [ONMARTECH LLC](https://onmartech.com)**

[](https://github.com/enessari/metabase-ai-assistant/stargazers)

---

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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [enessari](https://github.com/enessari)
- **Source:** [enessari/metabase-ai-assistant](https://github.com/enessari/metabase-ai-assistant)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-enessari-metabase-ai-assistant
- Seller: https://agentstack.voostack.com/s/enessari
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.