Readme: Metabase MCP Server

Ein umfassender Model Context Protocol (MCP)-Server für die Metabase-Integration, der KI-Assistenten vollen Zugriff auf die Analyseplattform von Metabase bietet.

🚀 Quick Start

# Install and run with npx
export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key
npx @cognitionai/metabase-mcp-server

Related MCP server: Metabase MCP Server

✨ Funktionen

🎯 81+ Tools verfügbar - Vollständige Metabase-API-Abdeckung

• 📊 Dashboard-Verwaltung (23 Tools) - Vollständige CRUD-Operationen, Kartenverwaltung, öffentliches Teilen, Einbettung

• 📈 Karten-/Fragenverwaltung (21 Tools) - Abfrageausführung, Parameterverwaltung, Pivot-Abfragen, öffentliche Links

• 🗄️ Datenbankverwaltung (13 Tools) - Verbindungsverwaltung, Schema-Synchronisierung, Abfrageausführung

• 📋 Tabellenverwaltung (16 Tools) - Metadatenoperationen, Feldverwaltung, Datenoperationen

• 🔍 Zusätzliche Tools (9 Tools) - Sammlungen, Suche, Benutzer, Aktivitätsverfolgung, Playground-Links

📦 Installation

💡 Empfohlen: Node.js 20.19.0+ und npm 8.0.0+ für optimale Kompatibilität

Methode 1: NPX (Empfohlen)

npx @cognitionai/metabase-mcp-server

Methode 2: Globale Installation

npm install -g @cognitionai/metabase-mcp-server
metabase-mcp-server

Methode 3: Docker

docker run -it --rm \
  -e METABASE_URL=https://your-metabase-instance.com \
  -e METABASE_API_KEY=your_metabase_api_key \
  ghcr.io/CognitionAI/metabase-mcp-server

⚙️ Konfiguration

Umgebungsvariablen

API-Schlüssel-Authentifizierung (bevorzugt):

export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key

Benutzername/Passwort-Authentifizierung (Fallback):

export METABASE_URL=https://your-metabase-instance.com
export METABASE_USERNAME=your_username
export METABASE_PASSWORD=your_password

Optionale Argumente

Der Server unterstützt Befehlszeilenargumente, um das Laden der Tools anzupassen:

• --essential (Standard): Nur die wichtigsten Tools laden

• --all: Alle 80+ verfügbaren Tools laden

• --write: Nur Schreib-/Änderungs-Tools laden

• --read: Nur Lese-Tools laden

# Using published package (recommended)
# Default behavior (essential tools only)
npx @cognitionai/metabase-mcp-server

# Load all tools
npx @cognitionai/metabase-mcp-server --all

# Load only write tools
npx @cognitionai/metabase-mcp-server --write

# Load only read-only tools
npx @cognitionai/metabase-mcp-server --read

# Using local development build
npm run build
node dist/server.js                    # Default (essential tools)
node dist/server.js --all             # All tools
node dist/server.js --write           # Write tools only
node dist/server.js --read            # Read-only tools only

🔌 Integrationsbeispiele

Claude Desktop

Fügen Sie Folgendes zu Ihrer Claude-Desktop-Konfiguration hinzu (~/Library/Application Support/Claude/claude_desktop_config.json auf macOS):

Mit veröffentlichtem Paket:

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

Mit lokalem Entwicklungs-Build:

{
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/path/to/metabase-mcp-server/dist/server.js"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

Mit benutzerdefinierten Flags:

{
  "mcpServers": {
    "metabase-all": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server", "--all"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

Windsurf IDE

Fügen Sie Folgendes zu Ihrer Windsurf-MCP-Konfiguration hinzu (~/.windsurf/mcp_config.json):

Mit veröffentlichtem Paket:

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

Mit lokalem Entwicklungs-Build:

{
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/path/to/metabase-mcp-server/dist/server.js"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

Mit benutzerdefinierten Flags:

{
  "mcpServers": {
    "metabase-read": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server", "--read"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    },
    "metabase-write": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server", "--write"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

🛠️ Verfügbare Tools

Kernoperationen

• list_dashboards - Alle Dashboards auflisten

• get_dashboard - Dashboard per ID abrufen

• create_dashboard - Neues Dashboard erstellen

• update_dashboard - Bestehendes Dashboard aktualisieren

• delete_dashboard - Dashboard löschen

• copy_dashboard - Dashboard kopieren

Kartenverwaltung

• get_dashboard_cards - Alle Karten im Dashboard abrufen

• add_card_to_dashboard - Karte zum Dashboard hinzufügen

• remove_card_from_dashboard - Karte aus Dashboard entfernen

• update_dashboard_card - Kartenposition/-einstellungen aktualisieren

• execute_dashboard_card - Bestimmte Dashboard-Karte ausführen

Öffentliches Teilen & Einbettung

• create_public_link - Öffentlichen Dashboard-Link erstellen

• delete_public_link - Öffentlichen Dashboard-Link löschen

• list_public_dashboards - Öffentliche Dashboards auflisten

• list_embeddable_dashboards - Einbettbare Dashboards auflisten

Parameter & Abfragen

• get_dashboard_param_values - Parameterwerte abrufen

• search_dashboard_param_values - Parameterwerte durchsuchen

• get_dashboard_param_remapping - Parameter-Neuzuordnung abrufen

• execute_dashboard_query - Dashboard-Abfragen ausführen

Erweiterte Funktionen

• get_dashboard_related - Zugehörige Inhalte abrufen

• get_dashboard_query_metadata - Abfragemetadaten abrufen

• update_dashboard_cards - Karten massenhaft aktualisieren

• save_dashboard - Dashboard-Änderungen speichern

• get_dashboard_items - Dashboard-Elemente abrufen

Kernoperationen

• list_cards - Alle Karten/Fragen auflisten

• get_card - Karte per ID abrufen

• create_card - Neue Karte erstellen

• update_card - Bestehende Karte aktualisieren

• delete_card - Karte löschen

• copy_card - Karte kopieren

Abfrageausführung

• execute_card - Kartenabfrage ausführen

• execute_card_query_with_format - Mit bestimmtem Format ausführen

• execute_pivot_card_query - Pivot-Abfrage ausführen

• get_card_query_metadata - Abfragemetadaten abrufen

Kartenverwaltung

• move_cards - Karten zwischen Sammlungen verschieben

• move_cards_to_collection - Massenhaft in Sammlung verschieben

• get_card_dashboards - Dashboards abrufen, die die Karte enthalten

• get_card_series - Kartenserien-Daten abrufen

Parameter & Werte

• get_card_param_values - Parameterwerte abrufen

• search_card_param_values - Parameterwerte durchsuchen

• get_card_param_remapping - Parameter-Neuzuordnung abrufen

Öffentliches Teilen

• create_card_public_link - Öffentlichen Kartenlink erstellen

• delete_card_public_link - Öffentlichen Kartenlink löschen

• get_public_cards - Öffentliche Karten auflisten

• get_embeddable_cards - Einbettbare Karten auflisten

Kernoperationen

• list_databases - Alle Datenbanken auflisten

• get_database - Datenbankdetails abrufen

• create_database - Datenbankverbindung erstellen

• update_database - Datenbankeinstellungen aktualisieren

• delete_database - Datenbankverbindung löschen

Schema & Metadaten

• get_database_schema_tables - Datenbanktabellen abrufen

• get_database_schemas - Datenbankschemas abrufen

• get_database_metadata - Vollständige Metadaten abrufen

• sync_database_schema - Schema-Metadaten synchronisieren

Abfrageoperationen

• execute_query - SQL-Abfragen ausführen

• execute_query_export - Abfragen ausführen und Ergebnisse exportieren

Wartung

• get_database_usage_info - Nutzungsstatistiken abrufen

• rescan_database_field_values - Feldwerte erneut scannen

Kernoperationen

• list_tables - Tabellen mit Filterung auflisten

• get_table - Tabellendetails abrufen

• update_table - Tabellenkonfiguration aktualisieren

• update_tables - Tabellen massenhaft aktualisieren

Datenoperationen

• get_table_data - Tabellendaten abrufen

• append_csv_to_table - CSV-Daten anhängen

• replace_table_csv - Mit CSV-Daten ersetzen

Schema & Beziehungen

• get_table_query_metadata - Abfragemetadaten abrufen

• get_table_fks - Fremdschlüsselbeziehungen abrufen

• get_table_related - Zugehörige Tabellen abrufen

• sync_table_schema - Tabellenschema synchronisieren

Feldverwaltung

• reorder_table_fields - Feldanzeige neu anordnen

• rescan_table_field_values - Feldwerte erneut scannen

• discard_table_field_values - Zwischengespeicherte Werte verwerfen

Kartenintegration

• get_card_table_fks - Fremdschlüssel der Kartentabelle abrufen

• get_card_table_query_metadata - Abfragemetadaten der Kartentabelle abrufen

Sammlungen

• list_collections - Alle Sammlungen auflisten

• create_collection - Neue Sammlung erstellen

• update_collection - Sammlung aktualisieren

• delete_collection - Sammlung löschen

• get_collection_items - Sammlungselemente abrufen

Suche & Entdeckung

• search_content - In allen Inhalten suchen

Aktivität & Analysen

• get_recent_views - Letzte Aktivität abrufen

• get_popular_items - Beliebte Inhalte abrufen

Playground-Links

• get_metabase_playground_link - Interaktive Playground-Links generieren

🧪 Entwicklung

Einrichtung

git clone https://github.com/CognitionAI/metabase-mcp-server.git
cd metabase-mcp-server
npm install

Build

npm run build

Entwicklungsmodus

npm run watch

Debugging

Verwenden Sie den MCP Inspector zum Debugging:

npm run inspector

🔍 Authentifizierung testen

API-Schlüssel-Authentifizierung

1. Setzen Sie METABASE_URL und METABASE_API_KEY

2. Starten Sie den Server und prüfen Sie in den Protokollen, dass „Using Metabase API Key“ angezeigt wird

3. Testen Sie mit dem list_dashboards-Tool

Benutzername/Passwort-Authentifizierung

1. Entfernen Sie METABASE_API_KEY

2. Setzen Sie METABASE_URL, METABASE_USERNAME, METABASE_PASSWORD

3. Starten Sie den Server und prüfen Sie in den Protokollen, dass „Using username/password“ angezeigt wird

4. Testen Sie mit dem list_dashboards-Tool

🐛 Fehlerbehebung

Häufige Probleme

Authentifizierungsfehler:

• Stellen Sie sicher, dass Ihre Metabase-URL erreichbar ist

• Prüfen Sie die Gültigkeit des API-Schlüssels in den Metabase-Admin-Einstellungen

• Stellen Sie sicher, dass die Benutzername-/Passwort-Anmeldedaten korrekt sind

Verbindungsprobleme:

• Bestätigen Sie, dass die Metabase-Instanz ausgeführt wird

• Prüfen Sie die Netzwerkverbindung

• Überprüfen Sie SSL-Zertifikate, wenn HTTPS verwendet wird

Fehler bei der Tool-Ausführung:

• Prüfen Sie die Metabase-Berechtigungen für Ihren Benutzer/API-Schlüssel

• Stellen Sie sicher, dass die angeforderte Ressource existiert

• Prüfen Sie die Serverprotokolle auf detaillierte Fehlermeldungen

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert - siehe LICENSE für Details.

🤝 Mitwirken

Beiträge sind willkommen! Besuchen Sie bitte unser GitHub-Repository, um:

• 🐛 Fehler zu melden

• 💡 Funktionen vorzuschlagen

• 🔧 Pull-Requests einzureichen

• 📖 Die Dokumentation zu verbessern

Entwicklungsrichtlinien

1. Repository forken

2. Einen Feature-Branch erstellen

3. Änderungen mit Tests vornehmen

4. Sicherstellen, dass alle Tests bestanden werden

5. Einen Pull-Request einreichen

🆘 Support

• 📚 Dokumentation

• 🐛 Issue-Tracker

Mit ❤️ für die Welt gebaut