telai-mcp

MCP Server für telefonieren.ai - Verwalte AI-Telefonagenten direkt aus Claude Desktop.

Features

• 121 Tools für die vollständige Verwaltung von:
  • AI Agents (11 Tools) - Erweitert mit Refresh, Transfer & Statistiken
  • Calls (10 Tools) - Bulk-Operations für Kategorien & Metadaten
  • Templates (5 Tools)
  • Contacts (8 Tools) - Vollständiges CRM mit CSV/Excel Import
  • Campaigns (6 Tools) - Bulk-Calling mit Dry-Run Support
  • Rules & Automation (10 Tools) - Ereignisgesteuerte Workflows & Rate Limiting
  • Phone Numbers (6 Tools) - Twilio Nummer-Provisioning & Management
  • Voices (3 Tools) - ElevenLabs & OpenAI Voice Library
  • Voice Preview (2 Tools) - Stimmen-Samples generieren
  • Hotlines (5 Tools) - Inbound-Routing mit Geschäftszeiten
  • Call Forwarding (1 Tool) - Weiterleitungsregeln aktualisieren
  • Media (4 Tools) - Audio/Bild Upload & TTS Generierung
  • Pronunciations (4 Tools) - Benutzerdefinierte Aussprache-Regeln
  • Integrations (7 Tools) - Nylas, Perplexity, Custom APIs & OAuth
  • Postprocessing (7 Tools) - Transkription, Zusammenfassungen, Sentiment-Analyse
  • DNC (5 Tools) - Do-Not-Call Listen-Management
  • Crawler (6 Tools) - Web-Crawling für URL-Collections
  • Channels (3 Tools) - Multi-Channel Kommunikation
  • Mailbox (2 Tools) - Voicemail & Callback-Anfragen
  • Knowledge Collections (7 Tools)
  • Documents (9 Tools) - inkl. Semantic Search & Bulk-Delete
• Type-safe mit TypeScript und Zod Validation
• Retry Logic mit Exponential Backoff
• File Upload für Contacts (CSV/Excel), Media (Audio/Bilder) & Documents (PDF/DOCX)
• Admin Features mit Permission-basierter Zugriffskontrolle
• Sentry Integration für Production Monitoring
• Claude Desktop kompatibel

Installation

Voraussetzungen

• Node.js v18 oder höher
• npm v9 oder höher
• Claude Desktop installiert
• API Keys von telefonieren.ai

Schritt 1: Repository klonen

git clone https://github.com/neuromanufaktur/telai-mcp.git
cd telai-mcp

Schritt 2: Dependencies installieren & builden

npm install
npm run build

Schritt 3: Claude Desktop konfigurieren

Die Konfiguration unterscheidet sich je nach Betriebssystem:

🪟 Windows

Config-Pfad: %APPDATA%\Claude\claude_desktop_config.json

Öffnen mit:

notepad $env:APPDATA\Claude\claude_desktop_config.json

Config hinzufügen:

{
  "mcpServers": {
    "telai-mcp": {
      "command": "node",
      "args": [
        "C:\\Users\\DEIN_USERNAME\\Desktop\\telai-mcp\\dist\\index.js"
      ],
      "env": {
        "TELAI_API_KEY": "dein-api-key",
        "KNOWLEDGE_API_KEY": "dein-api-key",
        "TELEFONIEREN_BASE_URL": "https://api.telefonieren.ai",
        "KNOWLEDGE_BASE_URL": "https://knowledge.neuromanufaktur.ai"
      }
    }
  }
}

⚠️ Wichtig: Ersetze DEIN_USERNAME mit deinem Windows-Benutzernamen und passe den Pfad an, wo du das Repository geklont hast. Benutze doppelte Backslashes \\ in Windows-Pfaden.

🍎 macOS

Config-Pfad: ~/Library/Application Support/Claude/claude_desktop_config.json

Öffnen mit:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Config hinzufügen:

{
  "mcpServers": {
    "telai-mcp": {
      "command": "node",
      "args": [
        "/Users/DEIN_USERNAME/code/telai-mcp/dist/index.js"
      ],
      "env": {
        "TELAI_API_KEY": "dein-api-key",
        "KNOWLEDGE_API_KEY": "dein-api-key",
        "TELEFONIEREN_BASE_URL": "https://api.telefonieren.ai",
        "KNOWLEDGE_BASE_URL": "https://knowledge.neuromanufaktur.ai"
      }
    }
  }
}

⚠️ Wichtig: Ersetze DEIN_USERNAME mit deinem macOS-Benutzernamen.

Falls Node über NVM installiert ist:

"command": "/Users/DEIN_USERNAME/.nvm/versions/node/v20.x.x/bin/node"

🐧 Linux

Config-Pfad: ~/.config/Claude/claude_desktop_config.json

Öffnen mit:

nano ~/.config/Claude/claude_desktop_config.json

Config hinzufügen:

{
  "mcpServers": {
    "telai-mcp": {
      "command": "node",
      "args": [
        "/home/DEIN_USERNAME/code/telai-mcp/dist/index.js"
      ],
      "env": {
        "TELAI_API_KEY": "dein-api-key",
        "KNOWLEDGE_API_KEY": "dein-api-key",
        "TELEFONIEREN_BASE_URL": "https://api.telefonieren.ai",
        "KNOWLEDGE_BASE_URL": "https://knowledge.neuromanufaktur.ai"
      }
    }
  }
}

⚠️ Wichtig: Ersetze DEIN_USERNAME mit deinem Linux-Benutzernamen.

Falls Node über NVM installiert ist:

"command": "/home/DEIN_USERNAME/.nvm/versions/node/v20.x.x/bin/node"

Schritt 4: Claude Desktop neu starten

Nach dem Speichern der Config muss Claude Desktop komplett neu gestartet werden:

• Windows: Task Manager → Claude beenden → Neu starten
• macOS: Cmd+Q → Neu starten
• Linux: killall Claude → Neu starten

Schritt 5: Verbindung testen

Öffne einen neuen Chat in Claude Desktop und frage:

Welche MCP Server sind verbunden?

Oder teste direkt:

Liste alle meine telefonieren.ai Agents

Umgebungsvariablen

| Variable | Erforderlich | Beschreibung | |----------|--------------|--------------| | TELAI_API_KEY | ✅ Ja | API Key von telefonieren.ai | | KNOWLEDGE_API_KEY | ✅ Ja | API Key für Knowledge Service (meist gleich wie TELAI_API_KEY) | | TELEFONIEREN_BASE_URL | ❌ Nein | Default: https://api.telefonieren.ai | | KNOWLEDGE_BASE_URL | ❌ Nein | Default: https://knowledge.neuromanufaktur.ai | | SENTRY_DSN | ❌ Nein | Für Error-Tracking (optional) |

Troubleshooting

"Server disconnected" Fehler

1. Prüfe den Pfad: Ist der Pfad zur dist/index.js korrekt?
2. Prüfe Node: Führe node --version aus - muss v18+ sein
3. NVM-Nutzer: Verwende den vollen Pfad zu Node (siehe oben)
4. Teste manuell:

   cd /pfad/zu/telai-mcp
   TELAI_API_KEY=xxx KNOWLEDGE_API_KEY=xxx node dist/index.js

"Invalid credentials" Fehler

• Prüfe ob der API Key korrekt ist
• API Keys erhältst du unter telefonieren.ai → Settings → API Keys

Server startet, aber keine Tools verfügbar

• Prüfe ob npm run build erfolgreich war
• Prüfe ob dist/index.js existiert

Alternative: npx (experimentell)

Sobald das Paket auf npm veröffentlicht ist:

{
  "mcpServers": {
    "telefonieren": {
      "command": "npx",
      "args": ["telai-mcp"],
      "env": {
        "TELAI_API_KEY": "dein-api-key",
        "KNOWLEDGE_API_KEY": "dein-api-key"
      }
    }
  }
}

Config-Pfade:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Verfügbare Tools

Agent Management (11 Tools)

| Tool | Beschreibung | |------|-------------| | list_agents | Alle Agents mit Filtering auflisten | | get_agent | Details eines Agents abrufen | | create_agent | Neuen Agent erstellen | | update_agent | Agent aktualisieren | | delete_agent | Agent löschen | | duplicate_agent | Agent duplizieren | | get_agent_stats | Agent-Statistiken abrufen | | list_child_agents | Kind-Agents auflisten | | refresh_agents | Agent-Konfigurationen vom Backend aktualisieren | | transfer_agent | Agent-Besitz übertragen (Admin) | | get_agent_statistics | Detaillierte Performance-Statistiken abrufen |

Call Management (10 Tools)

| Tool | Beschreibung | |------|-------------| | list_calls | Alle Calls mit Filtering auflisten | | initiate_call | Neuen Anruf starten | | get_call_details | Call-Details abrufen | | delete_call | Call löschen | | submit_call_feedback | Feedback einreichen | | get_call_feedback | Feedback abrufen | | cleanup_expired_calls | Abgelaufene Calls aufräumen | | mark_calls_as_read | Mehrere Calls als gelesen markieren (Bulk) | | update_call_categories | Call-Kategorien aktualisieren | | update_call_metadata | Call-Metadaten aktualisieren |

Template Management (5 Tools)

| Tool | Beschreibung | |------|-------------| | list_templates | Alle Templates auflisten | | get_template | Template-Details abrufen | | create_template | Neues Template erstellen | | update_template | Template aktualisieren | | delete_template | Template löschen |

Contact Management (8 Tools)

| Tool | Beschreibung | |------|-------------| | list_contacts | Alle Kontakte mit Filtering auflisten | | get_contact | Kontakt-Details abrufen | | create_contact | Neuen Kontakt erstellen | | update_contact | Kontakt aktualisieren | | delete_contact | Kontakt löschen | | bulk_delete_contacts | Mehrere Kontakte gleichzeitig löschen | | import_contacts | Kontakte aus CSV/Excel importieren (max 10MB) | | export_contacts | Kontakte als CSV/Excel exportieren |

Campaign Management (6 Tools)

| Tool | Beschreibung | |------|-------------| | list_campaigns | Alle Kampagnen mit Filtering auflisten | | get_campaign | Kampagnen-Details und Statistiken abrufen | | create_campaign | Neue Bulk-Calling Kampagne erstellen | | update_campaign | Kampagne aktualisieren | | delete_campaign | Kampagne löschen | | start_campaign | Kampagne starten (mit Dry-Run Support) |

Rules & Automation (10 Tools)

| Tool | Beschreibung | |------|-------------| | list_rules | Alle Automatisierungsregeln auflisten | | get_rule | Regel-Details abrufen | | create_rule | Neue Regel erstellen | | update_rule | Regel aktualisieren | | delete_rule | Regel löschen | | test_rule | Regel-Bedingungen testen | | list_rule_executions | Regel-Ausführungshistorie anzeigen | | get_rate_limit_settings | Rate-Limit Einstellungen abrufen | | update_rate_limit_settings | Rate-Limits konfigurieren | | check_rate_limit_status | Aktuellen Rate-Limit Status prüfen |

Phone Number Management (6 Tools)

| Tool | Beschreibung | |------|-------------| | list_phone_numbers | Alle Telefonnummern mit Filtering auflisten | | get_phone_number | Telefonnummer-Details abrufen | | provision_phone_number | Neue Nummer von Twilio bereitstellen | | release_phone_number | Nummer freigeben (Admin) | | update_phone_number | Telefonnummer-Einstellungen aktualisieren | | search_available_numbers | Verfügbare Nummern bei Twilio suchen |

Voice Management (3 Tools)

| Tool | Beschreibung | |------|-------------| | list_voices | Alle verfügbaren Stimmen (ElevenLabs, OpenAI) auflisten | | get_voice | Stimmen-Details und Sample-URL abrufen | | refresh_voices | Voice Library vom Provider aktualisieren |

Voice Preview (2 Tools)

| Tool | Beschreibung | |------|-------------| | generate_voice_preview | Stimmen-Sample mit Beispieltext generieren | | compare_voices | Mehrere Stimmen parallel vergleichen |

Hotline Management (5 Tools)

| Tool | Beschreibung | |------|-------------| | list_hotlines | Alle Inbound-Hotlines auflisten | | get_hotline | Hotline-Details abrufen | | create_hotline | Neue Hotline mit Geschäftszeiten erstellen | | update_hotline | Hotline aktualisieren | | delete_hotline | Hotline löschen |

Call Forwarding (1 Tool)

| Tool | Beschreibung | |------|-------------| | refresh_forwarding_rules | Weiterleitungsregeln vom Provider aktualisieren |

Media Management (4 Tools)

| Tool | Beschreibung | |------|-------------| | upload_media | Audio (MP3/WAV/OGG/M4A) oder Bild (PNG/JPG/GIF/WEBP) hochladen (max 10MB) | | get_media | Media-Details und Download-URL abrufen | | delete_media | Media-Datei löschen | | generate_tts_audio | Text-to-Speech Audio mit spezifischer Stimme generieren |

Pronunciation Management (4 Tools)

| Tool | Beschreibung | |------|-------------| | list_pronunciations | Alle benutzerdefinierten Aussprache-Regeln auflisten | | get_pronunciation | Aussprache-Regel-Details abrufen | | create_pronunciation | Neue Aussprache-Regel erstellen (z.B. "PostgreSQL" → "post-gress-Q-L") | | delete_pronunciation | Aussprache-Regel löschen |

Collection Management (7 Tools)

| Tool | Beschreibung | |------|-------------| | list_collections | Alle Collections auflisten | | create_collection | Neue Collection erstellen | | get_collection | Collection-Details abrufen | | update_collection | Collection aktualisieren | | delete_collection | Collection löschen | | refresh_collections | Collections neu einbetten | | transfer_collections | Collections übertragen |

Document Management (7 Tools)

| Tool | Beschreibung | |------|-------------| | list_documents | Dokumente in Collection auflisten | | get_document | Dokument-Details abrufen | | update_document | Dokument aktualisieren | | delete_document | Dokument löschen | | move_documents | Dokumente verschieben | | refresh_documents | Dokumente neu einbetten | | create_documents | Dokumente hochladen |

Beispiele

Agent erstellen und verwalten

"Erstelle einen neuen Agent namens 'Support Bot' mit der Sprache Deutsch"
"Zeige mir die Performance-Statistiken für Agent 'Support Bot'"
"Dupliziere den Agent 'Support Bot' als 'Sales Bot'"

Anruf starten und verwalten

"Rufe +49123456789 mit dem Agent 'Support Bot' an"
"Zeige mir alle Anrufe von gestern"
"Markiere die Calls mit IDs xyz als gelesen"

Kontakte und Kampagnen

"Importiere Kontakte aus der Datei kundenliste.csv"
"Erstelle eine Kampagne 'Produktlaunch' mit Agent 'Sales Bot'"
"Starte die Kampagne 'Produktlaunch' im Dry-Run Modus"

Telefonnummern und Stimmen

"Suche verfügbare deutsche Telefonnummern in Berlin"
"Zeige mir alle verfügbaren deutschen Stimmen"
"Generiere ein Stimmen-Sample für die Stimme 'Maria' mit dem Text 'Guten Tag'"

Hotlines und Weiterleitungen

"Erstelle eine Hotline für +49301234567 mit Geschäftszeiten Mo-Fr 9-17 Uhr"
"Liste alle aktiven Hotlines"
"Aktualisiere die Weiterleitungsregeln"

Media und Aussprache

"Lade die Audio-Datei begruessung.mp3 hoch"
"Generiere TTS Audio mit der Stimme 'Anton' für den Text 'Willkommen'"
"Füge eine Aussprache-Regel hinzu: PostgreSQL wird ausgesprochen als post-gress-Q-L"

Automatisierung

"Erstelle eine Regel: Wenn ein Anruf beendet ist, sende eine E-Mail"
"Liste alle Regel-Ausführungen der letzten 7 Tage"
"Zeige mir die aktuellen Rate-Limit Einstellungen"

Knowledge Base verwalten

"Liste alle Collections in meiner Knowledge Base"
"Lade die Datei produktkatalog.pdf in die Collection 'Produkte' hoch"
"Aktualisiere alle Dokumente in der Collection 'FAQ'"

Development

# Clone und Dependencies installieren
git clone <repo>
cd telai-mcp
npm install

# Development Server
npm run dev

# Build
npm run build

# Tests
npm test

Architektur

Übersicht

flowchart TB
    subgraph Client["MCP Client"]
        CD[Claude Desktop]
        CU[Cursor]
        OTHER[Andere MCP Clients]
    end

    subgraph Server["telai-mcp Server"]
        MCP[MCP Protocol Handler]
        TOOLS[Tool Registry]

        subgraph Clients["API Clients"]
            TC[TelefonierenClient]
            KC[KnowledgeClient]
        end
    end

    subgraph APIs["External APIs"]
        TAPI[api.telefonieren.ai]
        KAPI[knowledge.neuromanufaktur.ai]
    end

    CD <-->|stdio| MCP
    CU <-->|stdio| MCP
    OTHER <-->|stdio| MCP

    MCP --> TOOLS
    TOOLS --> TC
    TOOLS --> KC

    TC <-->|HTTPS| TAPI
    KC <-->|HTTPS| KAPI

Tool-Aufruf Sequenz

sequenceDiagram
    participant User
    participant Claude as Claude Desktop
    participant MCP as telai-mcp Server
    participant Tools as Tool Handler
    participant API as telefonieren.ai API

    User->>Claude: "Liste alle meine Agents"
    Claude->>MCP: tools/call: list_agents
    MCP->>Tools: Validate & Route
    Tools->>API: GET /agents/

    alt Success
        API-->>Tools: 200 OK + Agent List
        Tools-->>MCP: Format Response
        MCP-->>Claude: Tool Result (JSON)
        Claude-->>User: "Du hast 5 Agents: ..."
    else Error
        API-->>Tools: 4xx/5xx Error
        Tools-->>MCP: Formatted Error + Hint
        MCP-->>Claude: Error Response
        Claude-->>User: "Fehler: ... Tipp: ..."
    end

Agent erstellen mit Retry

sequenceDiagram
    participant Claude as Claude Desktop
    participant MCP as telai-mcp
    participant Val as Zod Validator
    participant Client as API Client
    participant API as telefonieren.ai

    Claude->>MCP: create_agent({name, prompt, ...})
    MCP->>Val: Validate Input

    alt Invalid Input
        Val-->>MCP: Validation Error
        MCP-->>Claude: {success: false, error: "..."}
    else Valid Input
        Val-->>MCP: OK
        MCP->>Client: prepareAgentData()
        Note over Client: Transform prompt to<br/>{user_prompt: "..."}

        loop Retry (max 3x)
            Client->>API: POST /agents/
            alt Success
                API-->>Client: 201 Created
                Client-->>MCP: Agent Data
                MCP-->>Claude: {success: true, agent_id: "..."}
            else Network Error
                API-->>Client: Timeout/Error
                Note over Client: Wait & Retry
            else 422 Validation Error
                API-->>Client: 422 Error
                Client-->>MCP: Error + Workaround
                MCP-->>Claude: {success: false, workaround: "Use Web UI"}
            end
        end
    end

Anruf initiieren

sequenceDiagram
    participant User
    participant Claude as Claude Desktop
    participant MCP as telai-mcp
    participant API as telefonieren.ai
    participant Phone as Telefon System

    User->>Claude: "Rufe +49123456789 an mit Agent 'Sales Bot'"
    Claude->>MCP: initiate_call({agent_id, recipient_number})

    MCP->>MCP: Validate UUID
    MCP->>API: POST /calls/
    API->>Phone: Initiate Call
    Phone-->>API: Call Started
    API-->>MCP: {id: "call-uuid", status: "initiated"}
    MCP-->>Claude: {success: true, call_id: "..."}
    Claude-->>User: "Anruf gestartet! Call-ID: ..."

    Note over Phone: Anruf läuft...

    User->>Claude: "Wie lief der Anruf?"
    Claude->>MCP: get_call_details({call_id})
    MCP->>API: GET /calls/{id}
    API-->>MCP: {status: "completed", duration: 120, ...}
    MCP-->>Claude: Call Details
    Claude-->>User: "Der Anruf dauerte 2 Minuten..."

Knowledge Base Upload

sequenceDiagram
    participant User
    participant Claude as Claude Desktop
    participant MCP as telai-mcp
    participant FS as File System
    participant API as Knowledge API
    participant Vector as Pinecone

    User->>Claude: "Lade produkte.pdf in Collection 'Katalog'"
    Claude->>MCP: create_documents({collection_id, file_paths})

    MCP->>FS: Read File
    FS-->>MCP: File Content (Buffer)

    MCP->>MCP: Validate File Type (.pdf ✓)
    MCP->>API: POST /collections/{id}/documents (multipart)

    API->>API: Parse PDF
    API->>API: Chunk Text
    API->>Vector: Create Embeddings
    Vector-->>API: Stored

    API-->>MCP: {successful_uploads: 1, chunks_created: 42}
    MCP-->>Claude: Upload Result
    Claude-->>User: "Dokument hochgeladen! 42 Chunks erstellt."

Projektstruktur

src/
├── index.ts           # MCP Server Entry Point
├── config.ts          # Configuration Management
├── clients/
│   ├── telefonieren.ts   # API Client für api.telefonieren.ai (55 Methoden)
│   └── knowledge.ts      # API Client für Knowledge API (14 Methoden)
├── tools/
│   ├── index.ts           # Tool Registry (89 Tools)
│   ├── agents.ts          # Agent Tools (11)
│   ├── calls.ts           # Call Tools (10)
│   ├── templates.ts       # Template Tools (5)
│   ├── contacts.ts        # Contact Tools (8) - CSV/Excel Import
│   ├── campaigns.ts       # Campaign Tools (6) - Bulk Calling
│   ├── rules.ts           # Rules & Automation Tools (10)
│   ├── numbers.ts         # Phone Number Tools (6) - Twilio
│   ├── voices.ts          # Voice Library Tools (3)
│   ├── voice-preview.ts   # Voice Preview Tools (2)
│   ├── hotlines.ts        # Hotline Tools (5)
│   ├── forwarding.ts      # Forwarding Tools (1)
│   ├── media.ts           # Media Management Tools (4)
│   ├── pronunciations.ts  # Pronunciation Tools (4)
│   ├── collections.ts     # Collection Tools (7)
│   └── documents.ts       # Document Tools (7)
├── utils/
│   ├── validation.ts  # Input Validation (UUID, etc.)
│   ├── errors.ts      # Error Handling & Formatting
│   └── logger.ts      # Logging (Sentry Integration)
└── types/
    ├── api.ts         # API Types (16 Interfaces)
    ├── index.ts       # Re-exports
    └── [...]          # Tool Types

Testing

Eine umfassende Test-Dokumentation mit Beispielen für alle 89 Tools findest du in TESTING.md.

Die Dokumentation enthält:

• Setup-Anleitung
• Test-Szenarien für typische Workflows
• Vollständige Tool-Checklisten
• Bekannte Einschränkungen und Troubleshooting
• Performance-Tipps

Version History

v2.0.0 (Current)

• 89 Tools (↑ von 34 Tools)
• Phase 1: Contact Management, Campaigns, Rules & Automation (30 neue Tools)
• Phase 2: Phone Numbers, Voices, Hotlines, Media, Pronunciations (25 neue Tools)
• File Upload Support für CSV/Excel Import und Media Upload
• Admin Features mit Permission-basierter Zugriffskontrolle
• Erweiterte Agent- und Call-Verwaltung

v1.0.0

• 34 Basis-Tools für Agents, Calls, Templates, Collections, Documents

License

MIT

Links

• telefonieren.ai
• MCP Protocol
• Claude Desktop
• Testing Guide
• Implementation Plan