{"id":30522963,"url":"https://github.com/enessari/metabase-ai-assistant","last_synced_at":"2026-02-12T00:19:02.179Z","repository":{"id":336569141,"uuid":"1133942118","full_name":"enessari/metabase-ai-assistant","owner":"enessari","description":"🚀 The most powerful MCP Server for Metabase - 111+ tools for AI SQL generation, dashboard automation \u0026 enterprise BI. Works with Claude, Cursor, ChatGPT.","archived":false,"fork":false,"pushed_at":"2026-02-05T07:09:10.000Z","size":1249,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-05T14:53:28.621Z","etag":null,"topics":["ai","assistant","business-intelligence","claude","cursor","llm","mcp","mcp-server","metabase","metabase-mcp","natural-language-sql","reporting","sql"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/enessari.png","metadata":{},"created_at":"2026-01-14T02:56:29.000Z","updated_at":"2026-02-05T07:09:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/enessari/metabase-ai-assistant","commit_stats":null,"previous_names":["enessari/metabase-ai-assistant"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/enessari/metabase-ai-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enessari%2Fmetabase-ai-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enessari%2Fmetabase-ai-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enessari%2Fmetabase-ai-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enessari%2Fmetabase-ai-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/enessari","download_url":"https://codeload.github.com/enessari/metabase-ai-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enessari%2Fmetabase-ai-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29350381,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T20:11:40.865Z","status":"ssl_error","status_checked_at":"2026-02-11T20:10:41.637Z","response_time":97,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","assistant","business-intelligence","claude","cursor","llm","mcp","mcp-server","metabase","metabase-mcp","natural-language-sql","reporting","sql"],"created_at":"2025-08-26T19:43:52.054Z","updated_at":"2026-02-12T00:19:02.159Z","avatar_url":"https://github.com/enessari.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Metabase AI Assistant 🤖\n\n[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)\n[![Node.js](https://img.shields.io/badge/Node.js-18+-brightgreen.svg)](https://nodejs.org/)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)\n[![GitHub stars](https://img.shields.io/github/stars/enessari/metabase-ai-assistant.svg?style=social\u0026label=Star)](https://github.com/enessari/metabase-ai-assistant/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/enessari/metabase-ai-assistant.svg?style=social\u0026label=Fork)](https://github.com/enessari/metabase-ai-assistant/forks)\n\nAI-powered assistant that connects to **Metabase** and **PostgreSQL databases** directly via **Model Context Protocol (MCP)** for **Claude Desktop** and **Claude Code**. Creates models, SQL queries, metrics, and dashboards using both Metabase API and direct database connections.\n\n\u003e 🚀 **MCP Server for Claude Desktop \u0026 Claude Code** - Metabase + Direct DB Access  \n\u003e ⭐ **If you find this project useful, please give it a star!** ⭐\n\n## 🚀 Features\n\n### 🔌 MCP Integration (Claude Desktop \u0026 Claude Code)\n- **Model Context Protocol**: Native integration with Claude Desktop and Claude Code\n- **Direct Database Access**: Direct PostgreSQL database connections\n- **Metabase API Integration**: Full integration with Metabase instances\n- **Schema Discovery**: Automatic database schema discovery and analysis\n- **Relationship Detection**: Table relationship detection and suggestions\n\n### 🤖 AI-Powered Features\n- **Natural Language SQL**: Generate SQL queries from natural language descriptions\n- **Smart Model Building**: AI-assisted Metabase model creation\n- **Intelligent Dashboards**: Automatic dashboard layout and widget suggestions\n- **Query Optimization**: SQL query performance optimization\n- **Data Insights**: Data analysis and pattern detection\n\n### 🛠️ Developer Tools\n- **DDL Operations**: Safe table/view/index creation (prefix-protected)\n- **Batch Operations**: Bulk data processing operations\n- **Connection Management**: Hybrid connection management (API + Direct)\n- **Security Controls**: AI object prefix control and approval workflows\n- **Performance Monitoring**: Operation timing and timeout controls\n\n## 📋 Requirements\n\n### 🖥️ System\n- **Node.js 18+**\n- **Claude Desktop** (for MCP support) OR **Claude Code**\n- **PostgreSQL Database** (for direct connections)\n\n### 🔗 Services\n- **Metabase instance** (v0.48+)\n- **Anthropic API** (included in Claude Desktop/Code)\n\n## 🔧 Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/onmartech/metabase-ai-assistant.git\ncd metabase-ai-assistant\n\n# Install dependencies\nnpm install\n\n# Create environment file\ncp .env.example .env\n```\n\n## ⚙️ Configuration\n\nEdit the `.env` file:\n\n```env\n# Metabase Configuration\nMETABASE_URL=http://your-metabase-instance.com\nMETABASE_USERNAME=your_username\nMETABASE_PASSWORD=your_password\nMETABASE_API_KEY=your_metabase_api_key\n\n# AI Provider (at least one required)\nANTHROPIC_API_KEY=your_anthropic_key\n# or\nOPENAI_API_KEY=your_openai_key\n\n# Application Settings\nLOG_LEVEL=info\n```\n\n⚠️ **Security Warning**: Never commit the `.env` file to version control. This file is already included in `.gitignore`.\n\n## 🔌 Claude Desktop \u0026 Claude Code Integration (MCP)\n\nThis project integrates with Claude Desktop and Claude Code via Model Context Protocol (MCP):\n\n### For Claude Desktop:\n\n1. **Edit Claude Desktop Config**: `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"metabase-ai-assistant\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/your/metabase-ai-assistant/src/mcp/server.js\"],\n      \"env\": {\n        \"METABASE_URL\": \"http://your-metabase-instance.com\",\n        \"METABASE_USERNAME\": \"your_username\",\n        \"METABASE_PASSWORD\": \"your_password\",\n        \"ANTHROPIC_API_KEY\": \"your_anthropic_key\"\n      }\n    }\n  }\n}\n```\n\n2. **Restart Claude Desktop** and MCP tools will be available.\n\n### For Claude Code:\n\nClaude Code can use this MCP server directly via global installation:\n\n#### Step 1: Global Installation\n```bash\n# Install the MCP server globally\nnpm link\n\n# Verify installation\nwhich metabase-ai-mcp\nnpm list -g | grep metabase-ai-assistant\n```\n\n#### Step 2: Environment Setup\nEnsure your `.env` file is properly configured with your Metabase credentials:\n\n```env\nMETABASE_URL=http://your-metabase-instance.com\nMETABASE_USERNAME=your_username\nMETABASE_PASSWORD=your_password\nMETABASE_API_KEY=your_api_key\nANTHROPIC_API_KEY=your_anthropic_key\n```\n\n#### Step 3: Test MCP Server\n```bash\n# Test the MCP server directly\nnode src/mcp/server.js\n\n# Test with environment variables\nexport METABASE_URL=\"http://your-instance.com\"\nexport METABASE_USERNAME=\"your_username\"\nexport METABASE_PASSWORD=\"your_password\"\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | node src/mcp/server.js\n```\n\n#### Step 4: Verify Integration\nIn Claude Code, ask: **\"What MCP tools do you have available?\"**\n\nYou should see **27 Metabase AI Assistant tools** available:\n\n**📊 Database Tools:**\n- `db_list` - List all Metabase databases\n- `db_schemas` - Get schema information  \n- `db_tables` - List tables with details\n- `sql_execute` - Run SQL queries\n\n**🎯 Metabase Tools:**\n- `mb_question_create` - Create questions/charts\n- `mb_dashboard_create` - Create dashboards\n- `mb_dashboard_template_executive` - Auto-generate executive dashboards\n- `mb_question_create_parametric` - Create parametric questions\n\n**🔍 AI-Powered Tools:**\n- `ai_sql_generate` - Generate SQL from natural language\n- `ai_sql_optimize` - Optimize SQL performance\n- `ai_sql_explain` - Explain SQL queries\n\n**📚 Documentation Tools:**\n- `web_explore_metabase_docs` - Crawl Metabase documentation\n- `web_search_metabase_docs` - Search documentation\n\nThe server provides comprehensive Metabase and PostgreSQL integration with **27 tools** for:\n- Database schema exploration and analysis\n- Natural language SQL query generation and optimization  \n- Executive dashboard templates and parametric questions\n- Direct DDL operations with security controls\n- Metabase documentation crawling and search\n- Table relationship detection and mapping\n\n## 🎯 Usage\n\n### Interactive CLI\n\n```bash\nnpm start\n```\n\n### Programmatic Usage\n\n```javascript\nimport { MetabaseClient } from './src/metabase/client.js';\nimport { MetabaseAIAssistant } from './src/ai/assistant.js';\n\n// Client oluştur\nconst client = new MetabaseClient({\n  url: 'http://your-metabase.com',\n  username: 'user',\n  password: 'pass'\n});\n\n// AI Assistant başlat\nconst assistant = new MetabaseAIAssistant({\n  metabaseClient: client,\n  aiProvider: 'anthropic',\n  anthropicApiKey: 'your-key'\n});\n\n// Model oluştur\nconst model = await assistant.createModel(\n  'Müşteri segmentasyon modeli',\n  databaseId\n);\n\n// SQL sorgusu üret\nconst sql = await assistant.generateSQL(\n  'Son 30 günün satış toplamı',\n  schema\n);\n```\n\n## 📚 Örnek Senaryolar\n\n### 1. E-Ticaret Dashboard'u\n\n```javascript\n// Satış modeli oluştur\nawait assistant.createModel(\n  'Günlük satış özeti - ürün, kategori, tutar',\n  databaseId\n);\n\n// Metrikler tanımla\nawait assistant.createMetric(\n  'Ortalama sepet değeri',\n  tableId\n);\n\n// Dashboard oluştur\nawait assistant.createDashboard(\n  'E-Ticaret Yönetici Paneli',\n  questions\n);\n```\n\n### 2. Müşteri Analizi\n\n```javascript\n// Müşteri segmentasyon sorgusu\nconst sql = await assistant.generateSQL(\n  'RFM analizi ile müşteri segmentleri',\n  schema\n);\n\n// Churn prediction modeli\nawait assistant.createModel(\n  'Müşteri kayıp tahmin modeli',\n  databaseId\n);\n```\n\n### 3. Finansal Raporlama\n\n```javascript\n// Gelir-gider analizi\nawait assistant.createQuestion(\n  'Aylık kar-zarar tablosu',\n  databaseId\n);\n\n// Bütçe karşılaştırma dashboard'u\nawait assistant.createDashboard(\n  'Bütçe vs Gerçekleşen',\n  budgetQuestions\n);\n```\n\n## 🛠️ CLI Komutları\n\nInteraktif CLI'da kullanılabilir komutlar:\n\n- **📊 Create Model**: AI ile model oluştur\n- **❓ Create Question**: SQL sorgusu oluştur\n- **📈 Create Metric**: Metrik tanımla\n- **📋 Create Dashboard**: Dashboard hazırla\n- **🔍 Explore Schema**: Veritabanı şemasını incele\n- **🚀 Execute SQL**: SQL sorgusu çalıştır\n- **🔧 Optimize Query**: Sorgu optimize et\n- **💡 AI Query Builder**: Doğal dilde sorgu oluştur\n\n## 📂 Proje Yapısı\n\n```\nmetabase-ai-assistant/\n├── src/\n│   ├── mcp/\n│   │   └── server.js        # MCP Server (Claude Desktop entegrasyonu)\n│   ├── metabase/\n│   │   └── client.js        # Metabase API client\n│   ├── database/\n│   │   ├── direct-client.js     # Direct PostgreSQL client\n│   │   └── connection-manager.js # Hybrid connection manager\n│   ├── ai/\n│   │   └── assistant.js     # AI helper functions\n│   ├── cli/\n│   │   └── interactive.js   # Interactive CLI (standalone)\n│   ├── utils/\n│   │   └── logger.js        # Logging utilities\n│   └── index.js             # Main entry point (CLI mode)\n├── tests/                    # Test files\n├── .env.example             # Environment template\n├── package.json\n└── README.md\n```\n\n## 🔍 API Referansı\n\n### MetabaseClient\n\n```javascript\n// Veritabanları\ngetDatabases()\ngetDatabase(id)\ngetDatabaseSchemas(databaseId)\ngetDatabaseTables(databaseId)\n\n// Modeller\ngetModels()\ncreateModel(modelData)\n\n// Sorgular\ngetQuestions(collectionId)\ncreateQuestion(questionData)\nexecuteNativeQuery(databaseId, sql)\n\n// Metrikler\ngetMetrics()\ncreateMetric(metricData)\n\n// Dashboard'lar\ngetDashboards()\ncreateDashboard(dashboardData)\naddCardToDashboard(dashboardId, cardId, options)\n```\n\n### MetabaseAIAssistant\n\n```javascript\n// AI İşlemleri\nanalyzeRequest(userRequest)\ngenerateSQL(description, schema)\nsuggestVisualization(data, questionType)\noptimizeQuery(sql)\nexplainQuery(sql)\n\n// Oluşturma İşlemleri\ncreateModel(description, databaseId)\ncreateQuestion(description, databaseId, collectionId)\ncreateMetric(description, tableId)\ncreateDashboard(description, questions)\n```\n\n## 🧪 Test\n\n```bash\n# Tüm testleri çalıştır\nnpm test\n\n# Bağlantı testi\nnpm run test:connection\n\n# Coverage raporu\nnpm run test:coverage\n```\n\n## 🔒 Security\n\n### Data Security\n- **Environment Variables**: All sensitive data (API keys, passwords) stored in `.env` file\n- **Git Ignore**: `.env` file excluded from version control\n- **SQL Injection Protection**: Parameterized queries and input validation\n- **Rate Limiting**: API request rate limiting applied\n- **Audit Logging**: All database operations logged for security monitoring\n- **No Hardcoded Credentials**: Security-first approach prevents credential exposure\n\n### Database Security\n- **AI Object Prefix**: All AI-created objects marked with `claude_ai_` prefix for safety\n- **Schema Isolation**: Operations limited to specified schemas only\n- **Read-Only Mode**: Default read-only permissions with explicit approval for modifications\n- **DDL Approval System**: Database changes require explicit confirmation\n- **Prefix Validation**: Only AI-prefixed objects can be modified or deleted\n\n### MCP Security\n- **Secure Transport**: MCP communication over secure channels\n- **Environment Isolation**: Credentials passed via environment variables\n- **Tool Validation**: All tool inputs validated before execution\n- **Error Handling**: Sensitive information filtered from error messages\n\n### Production Deployment\n- Use environment-specific configuration files\n- Prefer SSL/TLS connections for all database communications\n- Grant minimum required permissions to database users\n- Protect API endpoints with authentication and authorization\n- Regularly rotate API keys and database passwords\n- Monitor and log all tool usage for security auditing\n\n## 🐛 Troubleshooting\n\n### Connection Errors\n- Verify Metabase URL is accessible\n- Ensure API key and credentials are valid\n- Check network connectivity and firewall settings\n- Confirm environment variables are properly set\n\n### MCP Integration Issues\n- Ensure `npm link` was run successfully\n- Verify MCP server binary is in PATH: `which metabase-ai-mcp`\n- Check environment variables are exported: `echo $METABASE_URL`\n- Test MCP server directly: `node src/mcp/server.js`\n- Restart Claude Code after global installation\n\n### Query Errors\n- Validate SQL syntax and formatting\n- Verify table and column names exist\n- Check database permissions and schema access\n- Ensure proper schema selection for operations\n\n### Security Warnings\n- Never commit `.env` files to version control\n- Avoid hardcoding credentials in source code\n- Use prefix validation for AI-created objects\n- Monitor database operations for security compliance\n\n## 🚀 Production Deployment\n\n### Option 1: PM2 Process Manager (Recommended)\n```bash\n# Install PM2 globally\nnpm install -g pm2\n\n# Start MCP server with PM2\nnpm run pm2:start\n\n# Monitor and manage\nnpm run pm2:logs\nnpm run pm2:restart\nnpm run pm2:stop\n\n# Auto-restart on system reboot\npm2 startup\npm2 save\n```\n\n### Option 2: Docker Container\n```bash\n# Build and run with Docker Compose\nnpm run docker:run\n\n# Monitor logs\nnpm run docker:logs\n\n# Stop containers\nnpm run docker:stop\n```\n\n### Option 3: Cloud Deployment\n- **Railway**: One-click deploy with `railway.json`\n- **Heroku**: Deploy with Heroku CLI (see `deploy/heroku-deploy.md`)\n- **DigitalOcean**: App Platform with Docker\n- **AWS**: ECS Fargate or EC2 with systemd service\n\n### Option 4: Systemd Service (Linux)\n```bash\n# Copy service file\nsudo cp metabase-ai-mcp.service /etc/systemd/system/\n\n# Enable and start service\nsudo systemctl enable metabase-ai-mcp\nsudo systemctl start metabase-ai-mcp\n\n# Monitor service\nsudo systemctl status metabase-ai-mcp\nsudo journalctl -u metabase-ai-mcp -f\n```\n\n### Production Scripts\n```bash\nnpm run mcp:prod          # Production mode\nnpm run test:connection   # Health check\nnpm run lint             # Code quality check\n```\n\n## 📈 Roadmap\n\n- [ ] Natural Language Processing geliştirmeleri\n- [ ] Görsel sorgu builder\n- [ ] Otomatik dashboard öneri sistemi\n- [ ] Multi-database desteği\n- [ ] Real-time data streaming\n- [ ] Advanced ML modelleri\n\n## 🤝 Katkıda Bulunma\n\nBu projeyi beğendiyseniz ve geliştirmesine katkıda bulunmak istiyorsanız:\n\n### ⭐ Projeyi Destekleyin\n- **GitHub'da Star Verin**: Projeyi faydalı bulduysanız ⭐ star verin\n- **Follow Edin**: Güncellemelerden haberdar olmak için [@onmartech](https://github.com/onmartech) hesabını takip edin\n- **Share Edin**: Sosyal medyada paylaşın ve arkadaşlarınıza önerin\n\n### 🔧 Geliştirmeye Katılın\n1. **Fork** yapın\n2. **Feature branch** oluşturun (`git checkout -b feature/yeni-ozellik`)\n3. **Değişikliklerinizi** commit yapın (`git commit -m 'feat: Yeni özellik eklendi'`)\n4. **Push** yapın (`git push origin feature/yeni-ozellik`)\n5. **Pull Request** açın\n\n### 💡 Katkı Fikirleri\n- Yeni AI modeli entegrasyonları\n- Dashboard template'leri\n- Metabase connector'ları\n- Dokümantasyon iyileştirmeleri\n- Bug fixes ve performans optimizasyonları\n\n### 📋 Katkı Kuralları\n- Kod değişikliklerinde test yazın\n- Commit mesajlarında [Conventional Commits](https://conventionalcommits.org/) kullanın\n- ESLint ve Prettier ayarlarına uyun\n- Değişikliklerinizi dokümante edin\n\n## 📄 Lisans\n\nMIT License - Detaylar için [LICENSE](LICENSE) dosyasına bakın.\nCopyright (c) 2024 ONMARTECH LLC\n\n## 👥 Destek ve İletişim\n\n### 🐛 Bug Reports \u0026 Feature Requests\n- **GitHub Issues**: [Issues sayfası](https://github.com/onmartech/metabase-ai-assistant/issues)\n- **Bug Template**: Issue açarken template'leri kullanın\n- **Feature Requests**: Hangi özelliği istediğinizi detaylandırın\n\n### 💬 Topluluk\n- **GitHub Discussions**: Soru-cevap ve fikirler için\n- **Documentation**: Wiki sayfalarına katkı yapın\n- **Examples**: Örnek kullanım case'leri paylaşın\n\n### 🚀 Ticari Destek\nONMARTECH LLC tarafından profesyonel destek ve customization hizmetleri mevcuttur.\n\n## 🏆 Katkıda Bulunanlar\n\nBu projeyi mümkün kılan herkese teşekkürler:\n\n- **ONMARTECH LLC** - Proje geliştirme ve bakım\n- **Metabase Team** - Harika platform\n- **Open Source Community** - Sürekli ilham ve geri bildirim\n\n### 🌟 Hall of Fame\nÖnemli katkılarda bulunan geliştiriciler burada listelenecektir.\n\n**Bu projeyi faydalı bulduysanız ⭐ star vermeyi ve 🔄 share etmeyi unutmayın!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenessari%2Fmetabase-ai-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fenessari%2Fmetabase-ai-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenessari%2Fmetabase-ai-assistant/lists"}