metabase-ai-assistant

@enessari/metabase-ai-assistant

0 Stars 174 次浏览 enessari 更新于 2026-08-23

该服务暂未提供标准配置，请参考 README 手动接入

服务介绍

Metabase AI Assistant

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

MCP Server for Claude Desktop & Claude Code - Metabase + Direct DB Access
If you find this project useful, please give it a star!

Features

MCP Integration (Claude Desktop & Claude Code)

Model Context Protocol: Native integration with Claude Desktop and Claude Code
Direct Database Access: Direct PostgreSQL database connections
Metabase API Integration: Full integration with Metabase instances
Schema Discovery: Automatic database schema discovery and analysis
Relationship Detection: Table relationship detection and suggestions

AI-Powered Features

Natural Language SQL: Generate SQL queries from natural language descriptions
Smart Model Building: AI-assisted Metabase model creation
Intelligent Dashboards: Automatic dashboard layout and widget suggestions
Query Optimization: SQL query performance optimization
Data Insights: Data analysis and pattern detection

Developer Tools

DDL Operations: Safe table/view/index creation (prefix-protected)
Batch Operations: Bulk data processing operations
Connection Management: Hybrid connection management (API + Direct)
Security Controls: AI object prefix control and approval workflows
Performance Monitoring: Operation timing and timeout controls

Requirements

System

Node.js 18+
Claude Desktop (for MCP support) OR Claude Code
PostgreSQL Database (for direct connections)

Services

Metabase instance (v0.48+)
Anthropic API (included in Claude Desktop/Code)

Installation

# Clone the repository
git clone https://github.com/onmartech/metabase-ai-assistant.git
cd metabase-ai-assistant

# Install dependencies
npm install

# Create environment file
cp .env.example .env

Configuration

Edit the .env file:

# Metabase Configuration
METABASE_URL=http://your-metabase-instance.com
METABASE_USERNAME=your_username
METABASE_PASSWORD=your_password
METABASE_API_KEY=your_metabase_api_key

# AI Provider (at least one required)
ANTHROPIC_API_KEY=your_anthropic_key
# or
OPENAI_API_KEY=your_openai_key

# Application Settings
LOG_LEVEL=info

Security Warning: Never commit the .env file to version control. This file is already included in .gitignore.

Claude Desktop & Claude Code Integration (MCP)

This project integrates with Claude Desktop and Claude Code via Model Context Protocol (MCP):

For Claude Desktop:

Edit Claude Desktop Config: ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "metabase-ai-assistant": {
      "command": "node",
      "args": ["/path/to/your/metabase-ai-assistant/src/mcp/server.js"],
      "env": {
        "METABASE_URL": "http://your-metabase-instance.com",
        "METABASE_USERNAME": "your_username",
        "METABASE_PASSWORD": "your_password",
        "ANTHROPIC_API_KEY": "your_anthropic_key"
      }
    }
  }
}

Restart Claude Desktop and MCP tools will be available.

For Claude Code:

Claude Code can use this MCP server directly via global installation:

Step 1: Global Installation

# Install the MCP server globally
npm link

# Verify installation
which metabase-ai-mcp
npm list -g | grep metabase-ai-assistant

Step 2: Environment Setup

Ensure your .env file is properly configured with your Metabase credentials:

METABASE_URL=http://your-metabase-instance.com
METABASE_USERNAME=your_username
METABASE_PASSWORD=your_password
METABASE_API_KEY=your_api_key
ANTHROPIC_API_KEY=your_anthropic_key

Step 3: Test MCP Server

# Test the MCP server directly
node src/mcp/server.js

# Test with environment variables
export METABASE_URL="http://your-instance.com"
export METABASE_USERNAME="your_username"
export METABASE_PASSWORD="your_password"
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node src/mcp/server.js

Step 4: Verify Integration

In Claude Code, ask: "What MCP tools do you have available?"

You should see 27 Metabase AI Assistant tools available:

** Database Tools:**

db_list - List all Metabase databases
db_schemas - Get schema information
db_tables - List tables with details
sql_execute - Run SQL queries

** Metabase Tools:**

mb_question_create - Create questions/charts
mb_dashboard_create - Create dashboards
mb_dashboard_template_executive - Auto-generate executive dashboards
mb_question_create_parametric - Create parametric questions

** AI-Powered Tools:**

ai_sql_generate - Generate SQL from natural language
ai_sql_optimize - Optimize SQL performance
ai_sql_explain - Explain SQL queries

** Documentation Tools:**

web_explore_metabase_docs - Crawl Metabase documentation
web_search_metabase_docs - Search documentation

The server provides comprehensive Metabase and PostgreSQL integration with 27 tools for:

Database schema exploration and analysis
Natural language SQL query generation and optimization
Executive dashboard templates and parametric questions
Direct DDL operations with security controls
Metabase documentation crawling and search
Table relationship detection and mapping

Usage

Interactive CLI

npm start

Programmatic Usage

import { MetabaseClient } from './src/metabase/client.js';
import { MetabaseAIAssistant } from './src/ai/assistant.js';

// Client olutur
const client = new MetabaseClient({
  url: 'http://your-metabase.com',
  username: 'user',
  password: 'pass'
});

// AI Assistant balat
const assistant = new MetabaseAIAssistant({
  metabaseClient: client,
  aiProvider: 'anthropic',
  anthropicApiKey: 'your-key'
});

// Model olutur
const model = await assistant.createModel(
  'Mteri segmentasyon modeli',
  databaseId
);

// SQL sorgusu ret
const sql = await assistant.generateSQL(
  'Son 30 gnn sat toplam',
  schema
);

rnek Senaryolar

1. E-Ticaret Dashboard'u

// Sat modeli olutur
await assistant.createModel(
  'Gnlk sat zeti - rn, kategori, tutar',
  databaseId
);

// Metrikler tanmla
await assistant.createMetric(
  'Ortalama sepet deeri',
  tableId
);

// Dashboard olutur
await assistant.createDashboard(
  'E-Ticaret Ynetici Paneli',
  questions
);

2. Mteri Analizi

// Mteri segmentasyon sorgusu
const sql = await assistant.generateSQL(
  'RFM analizi ile mteri segmentleri',
  schema
);

// Churn prediction modeli
await assistant.createModel(
  'Mteri kayp tahmin modeli',
  databaseId
);

3. Finansal Raporlama

// Gelir-gider analizi
await assistant.createQuestion(
  'Aylk kar-zarar tablosu',
  databaseId
);

// Bte karlatrma dashboard'u
await assistant.createDashboard(
  'Bte vs Gerekleen',
  budgetQuestions
);

CLI Komutlar

Interaktif CLI'da kullanlabilir komutlar:

** Create Model**: AI ile model olutur
** Create Question**: SQL sorgusu olutur
** Create Metric**: Metrik tanmla
** Create Dashboard**: Dashboard hazrla
** Explore Schema**: Veritaban emasn incele
** Execute SQL**: SQL sorgusu altr
** Optimize Query**: Sorgu optimize et
** AI Query Builder**: Doal dilde sorgu olutur

Proje Yaps

metabase-ai-assistant/
 src/
    mcp/
       server.js        # MCP Server (Claude Desktop entegrasyonu)
    metabase/
       client.js        # Metabase API client
    database/
       direct-client.js     # Direct PostgreSQL client
       connection-manager.js # Hybrid connection manager
    ai/
       assistant.js     # AI helper functions
    cli/
       interactive.js   # Interactive CLI (standalone)
    utils/
       logger.js        # Logging utilities
    index.js             # Main entry point (CLI mode)
 tests/                    # Test files
 .env.example             # Environment template
 package.json
 README.md

API Referans

MetabaseClient

// Veritabanlar
getDatabases()
getDatabase(id)
getDatabaseSchemas(databaseId)
getDatabaseTables(databaseId)

// Modeller
getModels()
createModel(modelData)

// Sorgular
getQuestions(collectionId)
createQuestion(questionData)
executeNativeQuery(databaseId, sql)

// Metrikler
getMetrics()
createMetric(metricData)

// Dashboard'lar
getDashboards()
createDashboard(dashboardData)
addCardToDashboard(dashboardId, cardId, options)