Ambivo Claude MCP Server

Dieser Claude MCP (Model Context Protocol) Server ermöglicht den Zugriff auf Ambivo-API-Endpunkte für natürliche Sprachabfragen von Entitätsdaten mit Claude AI.

Funktionen

• Natürliche Sprachabfragen: Führen Sie natürliche Sprachabfragen gegen Entitätsdaten über den /entity/natural_query-Endpunkt aus

• JWT-Authentifizierung: Sicherer Zugriff mittels Bearer-Token-Authentifizierung

• Rate-Limiting: Integriertes Rate-Limiting zur Verhinderung von API-Missbrauch

• Token-Caching: Effiziente Token-Validierung mit Caching

• Fehlerbehandlung: Umfassende Fehlerbehandlung mit detaillierten Fehlermeldungen

• Wiederholungslogik: Automatische Wiederholung mit exponentiellem Backoff bei fehlgeschlagenen Anfragen

Tools

1. set_auth_token

Setzen Sie das JWT-Bearer-Token für die Authentifizierung mit der Ambivo-API.

Parameter:

• token (string, erforderlich): JWT-Bearer-Token

Verwendung:

{
  "token": "your-jwt-token-here"
}

2. natural_query

Führen Sie natürliche Sprachabfragen gegen Ambivo-Entitätsdaten aus.

Parameter:

• query (string, erforderlich): Natürliche Sprachabfrage, die beschreibt, welche Daten Sie möchten

• response_format (string, optional): Antwortformat – „table", „natural" oder „both" (Standard: „both")

Beispielabfragen:

• „Zeig mir Leads, die diese Woche erstellt wurden"

• „Finde Kontakte mit Gmail-Adressen"

• „Liste Opportunities mit einem Wert von mehr als 10.000 $ auf"

• „Zeig mir Leads mit attribution_source google_ads aus den letzten 7 Tagen"

Verwendung:

{
  "query": "Show me leads created this week with attribution_source google_ads",
  "response_format": "both"
}

Über

Dies ist eine reine Claude-basierte MCP-Server-Implementierung für die Ambivo-API, die für die nahtlose Zusammenarbeit mit Claude Desktop und anderen Claude-kompatiblen MCP-Clients entwickelt wurde. Sie ermöglicht die Interaktion mit Ihren Ambivo-CRM-Daten in natürlicher Sprache durch die leistungsstarken Sprachverständnisfähigkeiten von Claude.

Installation

Option 1: Installation von PyPI (empfohlen)

pip install ambivo-mcp-server

Option 2: Installation aus dem Quellcode

git clone https://github.com/ambivo-corp/ambivo-mcp-server.git
cd ambivo-mcp-server
pip install -e .

Server ausführen

# If installed via pip
ambivo-mcp-server

# Or using Python module
python -m ambivo_mcp_server.server

Konfiguration

Der Server verwendet die folgende Standardkonfiguration:

• Basis-URL: https://goferapi.ambivo.com

• Timeout: 30 Sekunden

• Inhaltstyp: application/json

Sie können diese Einstellungen bei Bedarf in der AmbivoAPIClient-Klasse ändern.

Authentifizierung

1. Setzen Sie zuerst Ihr Authentifizierungstoken mit dem set_auth_token-Tool

2. Das Token wird in allen nachfolgenden API-Anfragen als Bearer-Token eingefügt

3. Das Token sollte ein gültiges JWT-Token aus Ihrer Ambivo-API-Authentifizierung sein

Fehlerbehandlung

Der Server bietet eine umfassende Fehlerbehandlung:

• Authentifizierungsfehler: Klare Meldungen, wenn das Token fehlt oder ungültig ist

• HTTP-Fehler: Detaillierte HTTP-Statuscodes und Antwortmeldungen

• Validierungsfehler: Parametervalidierung mit hilfreichen Fehlermeldungen

• Netzwerkfehler: Timeout- und Verbindungsfehlerbehandlung

API-Endpunkte

Dieser MCP-Server arbeitet mit diesen Ambivo-API-Endpunkten:

/entity/natural_query

• Methode: POST

• Zweck: Verarbeitung natürlicher Sprachabfragen für den Abruf von Entitätsdaten

• Authentifizierung: Erforderlich (JWT-Bearer-Token)

• Inhaltstyp: application/json

/entity/data

• Methode: POST

• Zweck: Direkter Zugriff auf Entitätsdaten mit strukturierten Parametern

• Authentifizierung: Erforderlich (JWT-Bearer-Token)

• Inhaltstyp: application/json

Beispiel-Workflow

1. Authentifizierung setzen:

   {
     "tool": "set_auth_token",
     "arguments": {
       "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
     }
   }

2. Natürliche Sprachabfrage:

   {
     "tool": "natural_query", 
     "arguments": {
       "query": "Show me all leads created in the last 30 days with phone numbers",
       "response_format": "both"
     }
   }

3. Direkte Entitätsabfrage:

   {
     "tool": "entity_data",
     "arguments": {
       "entity_type": "contact",
       "filters": {"email": {"$regex": "@gmail.com$"}},
       "limit": 100,
       "sort": {"created_date": -1}
     }
   }

Entwicklung

Um diesen MCP-Server zu erweitern:

1. Neue Tools hinzufügen: Implementieren Sie zusätzliche Tools in den Funktionen handle_list_tools() und handle_call_tool()

2. API-Client ändern: Erweitern Sie die AmbivoAPIClient-Klasse, um zusätzliche Endpunkte zu unterstützen

3. Konfiguration aktualisieren: Ändern Sie die Standardeinstellungen im Konfigurationsabschnitt

Fehlerbehebung

Häufige Probleme:

1. Fehler „Authentifizierung erforderlich": Stellen Sie sicher, dass Sie zuerst set_auth_token aufgerufen haben

2. HTTP-401/403-Fehler: Überprüfen Sie, ob Ihr JWT-Token gültig und nicht abgelaufen ist

3. Verbindungs-Timeout: Überprüfen Sie die Netzwerkverbindung und die Verfügbarkeit des API-Endpunkts

4. Ungültige Parameter: Überprüfen Sie die Tool-Schemas auf erforderliche und optionale Parameter

Protokollierung:

Der Server protokolliert wichtige Ereignisse und Fehler. Überprüfen Sie die Konsolenausgabe für Debugging-Informationen.