de en es ja ko ru zh

LiveKit MCP Server

Name: LiveKit MCP Server
Author: Mantracare-Org

by Mantracare-Org

Overview Schema Source Related Servers Discussions Admin

Python

Remote

LiveKit MCP Server

Python MCP Code style: ruff Tests

Ein Hochleistungs-Server für das Model Context Protocol (MCP 2.0), der KI-Agenten mit der LiveKit Voice- und Telefonie-Engine von MantraCare verbindet.

Architektur • Schnellstart • Konfiguration • MCP-Clients verbinden • Authentifizierung • Verfügbare Tools • Entwicklung

📖 Übersicht

Der LiveKit MCP Server ermöglicht es LLMs und KI-Codierungsassistenten (wie Antigravity, Claude, Cursor und benutzerdefinierten Agenten), Sprachtelefonie-Pipelines, die von LiveKit (~/lkt) betrieben und über Mantra Auth (~/mantra-auth) authentifiziert werden, sicher zu steuern, zu überwachen und auszulösen.

Hauptfunktionen

🚀 MCP-2.0-Konformität: Basierend auf dem offiziellen Python-mcp-SDK mit Server-Sent Events (SSE) und Streamable-HTTP-Transports.
🔐 OAuth 2.1 & gemeinsames JWT: Native HS256-JWT-Validierung passend zu mantra-auth, mit Unterstützung für sowohl Authorization: Bearer-Header als auch ?token=-Abfrageparameter.
⚡ Blitzschneller Async-Kern: Unterstützt durch Starlette, Uvicorn und uv-Paketverwaltung.
🧩 Modulare Tool-Architektur: Domänengetrennte Tools für Telefonie, Anrufanalysen, Wissensdatenbanksuche und SIP-Trunking.
🧠 Agentisches Gedächtnis: Vollständige Obsidian-Wissensdatenbank (obsidian/) und AGENTS.md-Regeln zur Erhaltung des Kontexts für KI-Pair-Programming.

Related MCP server: Agent Identity MCP Server

🏛️ Systemarchitektur

┌─────────────────────────────────────────────────────────────┐
│ AI Client (Cursor / Claude / Antigravity / Web Agent)       │
└──────────────────────────────┬──────────────────────────────┘
                               │ 1. Bearer Token / ?token= (OAuth 2.1)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ [3. mantra-auth (:3000)]                                    │
│ Next.js + Prisma OAuth 2.1 Authorization Server             │
│ - Issues HS256 JWTs and verifies via /api/oauth/introspect  │
└──────────────────────────────┬──────────────────────────────┘
                               │ Shared JWT Secret Verification
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ [2. livekit-mcp (:8000)] (This Server)                      │
│ - Starlette ASGI + MCP 2.0 SSE Transport                    │
│ - Pure ASGI Auth Middleware (HS256 JWT validation)          │
│ - Public Endpoints: /health, /                              │
│ - Protected Endpoints: /sse, /messages                      │
│ - Registered Tools: greet_user, [Telephony/KB/SIP coming]   │
└──────────────────────────────┬──────────────────────────────┘
                               │ 2. Async HTTP (REST)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ [1. lkt (:8081)]                                            │
│ MantraCare LiveKit Voice Agent & Telephony Engine           │
│ - SIP Trunks (Plivo, Zadarma, VoiceLink, Twilio)            │
│ - LiveKit Cloud WebRTC Rooms & STT→LLM→TTS Voice Pipeline   │
│ - PostgreSQL (call_logs, kb_pages) & Redis (queues, locks)  │
└─────────────────────────────────────────────────────────────┘

📁 Repository-Struktur

livekit-mcp/
├── .env.example                # Sample environment variables
├── .gitignore                  # Git ignore definitions
├── .python-version             # Python version pin (3.11)
├── AGENTS.md                   # Agent Memory instructions
├── dev.sh                      # Development startup script
├── pyproject.toml              # UV package specification & build settings
├── uv.lock                     # Deterministic lockfile
├── README.md                   # Project documentation
│
├── obsidian/                   # Permanent Agentic Knowledge Base
│   ├── Home.md                 # Project navigation hub
│   ├── Architecture/           # System design, data flow, security & APIs
│   ├── Context/                # Stack, project summary & repository map
│   ├── Development/            # Sprint tracking, TODO & Changelog
│   ├── Features/               # Feature specifications (tools, auth)
│   └── Knowledge/              # Coding standards & architectural conventions
│
├── src/
│   └── livekit_mcp/
│       ├── __init__.py
│       ├── config.py           # Pydantic Settings & environment validation
│       ├── server.py           # MCPServer & Starlette app factory
│       ├── main.py             # CLI runner with Uvicorn
│       ├── auth/
│       │   ├── __init__.py
│       │   ├── jwt.py          # HS256 JWT decoding & claims validation
│       │   └── middleware.py   # Pure ASGI auth middleware (headers & ?token=)
│       ├── clients/
│       │   ├── __init__.py
│       │   ├── lkt_client.py   # Async HTTP client for lkt FastAPI (:8081)
│       │   └── auth_client.py  # Async HTTP client for mantra-auth (:3000)
│       └── tools/
│           ├── __init__.py
│           └── greeting.py     # Initial `greet_user` verification tool
│
└── tests/
    ├── __init__.py
    ├── conftest.py             # Fixtures for tokens, settings & test client
    ├── test_config.py          # Configuration unit tests
    ├── test_auth.py            # JWT verification & claims unit tests
    ├── test_greeting.py        # Tool registration & execution tests
    └── test_server.py          # Endpoints, SSE & Auth integration tests

🚀 Schnellstart

1. Voraussetzungen

Python: 3.11 oder höher
uv: Schneller Python-Paketmanager (uv installieren)
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```

2. Installation & Einrichtung

Repository klonen und in das Verzeichnis wechseln:
```
cd ~/livekit-mcp
```
Umgebungskonfiguration erstellen:
```
cp .env.example .env
```
Abhängigkeiten mit uv installieren:
```
uv sync
```

3. Server ausführen

Entwicklungsserver mit automatischem Neuladen starten:

./dev.sh

Oder direkt mit uv ausführen:

uv run python -m livekit_mcp.main

Der Server ist erreichbar unter http://localhost:8000.

⚙️ Konfiguration

Alle Einstellungen werden in src/livekit_mcp/config.py mit pydantic-settings verwaltet und aus .env geladen:

Variable	Typ	Standard	Beschreibung
`HOST`	string	`0.0.0.0`	Server-Bindeadresse
`PORT`	integer	`8000`	Lauschport des Servers
`ENVIRONMENT`	string	`development`	`development`, `test` oder `production`
`LOG_LEVEL`	string	`INFO`	Protokollierungsstufe (`DEBUG`, `INFO`, `WARNING`, `ERROR`)
`AUTH_ENABLED`	boolean	`true`	Erzwingt die JWT-Authentifizierung an geschützten Endpunkten
`JWT_SECRET`	string	`your-super-secret-...`	Gemeinsamer geheimer Schlüssel für die HS256-JWT-Signaturprüfung
`JWT_ALGORITHM`	string	`HS256`	JWT-Signaturalgorithmus (entspricht `mantra-auth`)
`AUTH_SERVER_URL`	string	`http://localhost:3000`	Basis-URL des Mantra-Auth-Servers
`JWT_ISSUER`	string	`http://localhost:3000`	Erwarteter JWT-Ausstelleranspruch (`iss`)
`JWT_AUDIENCE`	string	(leer)	Optionaler erwarteter Zielgruppenanspruch (`aud`)
`LKT_API_BASE_URL`	string	`http://localhost:8081`	Basis-URL der LKT-Voice-Agent-API
`LKT_API_TIMEOUT`	float	`15.0`	HTTP-Request-Timeout in Sekunden für LKT-Aufrufe
`LIVEKIT_URL`	string	(leer)	Direkte LiveKit-Cloud-WebSocket-URL (optional)
`LIVEKIT_API_KEY`	string	(leer)	Direkter LiveKit-Cloud-API-Schlüssel (optional)
`LIVEKIT_API_SECRET`	string	(leer)	Direktes LiveKit-Cloud-API-Geheimnis (optional)

📡 Endpunkte

Endpunkt	Methode	Authentifizierung	Beschreibung
`/health`	`GET`	❌ Nein	Öffentlicher Gesundheits- und Bereitschaftscheck mit Servicestatus
`/`	`GET`	❌ Nein	Servicestatus und Endpunkt-Metadaten
`/sse`	`GET`	✅ Ja	Öffnet einen dauerhaften Server-Sent-Events(SSE)-Stream für MCP-Clients
`/messages`	`POST`	✅ Ja	JSON-RPC-2.0-Endpunkt für MCP-Anfragen (Tool-Ausführung, Auflistungen)

Beispiel für den Gesundheitscheck

curl http://localhost:8000/health

{
  "status": "healthy",
  "service": "livekit-mcp",
  "version": "0.1.0",
  "auth_enabled": true,
  "environment": "development",
  "lkt_api_configured": true,
  "timestamp": "2026-08-20T12:30:00.000000+00:00"
}

🔐 Authentifizierung

Der Server implementiert OAuth 2.1 / HS256 Shared JWT Authentication, kompatibel mit mantra-auth.

Anmeldedaten bereitstellen

Authorization-Header (Standard):

GET /sse HTTP/1.1
Host: localhost:8000
Authorization: Bearer <your-jwt-access-token>

Abfrageparameter (für SSE-/EventSource-Clients):

GET /sse?token=<your-jwt-access-token> HTTP/1.1
Host: localhost:8000

Erwartete JWT-Ansprüche

{
  "sub": "user-123",
  "aud": "client-app",
  "iss": "http://localhost:3000",
  "exp": 1755694800,
  "iat": 1755691200,
  "scope": "openid profile telephony:call",
  "token_type": "access_token"
}

Entwicklungstipp: Setzen Sie AUTH_ENABLED=false in der .env-Datei, um die Token-Überprüfung während lokaler Tests zu deaktivieren.

🛠️ Verfügbare Tools

1. `greet_user`

Ein Verifizierungstool, das die MCP-Konnektivität, Parameteranalyse und den Serverstatus validiert.

Parameter:
- name (Zeichenkette, erforderlich): Name des Benutzers oder Agenten, der das Tool aufruft.
- message (Zeichenkette, optional): Benutzerdefinierte Begrüßungsnachricht.

Rückgabewert:

👋 Hello, Alice!

Welcome to MantraCare LiveKit MCP!

--- System Status ---
• Service: LiveKit MCP Server
• Status: Operational & Ready
• Timestamp: 2026-08-20T12:30:00.000000+00:00
• Protocol: MCP 2.0 (SSE / HTTP)

🔌 MCP-Clients verbinden

1. Antigravity / Gemini CLI (`~/.gemini/config/mcp_config.json`)

{
  "mcpServers": {
    "livekit": {
      "serverUrl": "http://localhost:8000/sse"
    }
  }
}

2. Cursor IDE (`.cursor/mcp.json`)

{
  "mcpServers": {
    "livekit": {
      "url": "http://localhost:8000/sse",
      "headers": {
        "Authorization": "Bearer <YOUR_JWT_TOKEN>"
      }
    }
  }
}

3. Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "livekit": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/fardeen/livekit-mcp",
        "run",
        "python",
        "-m",
        "livekit_mcp.main"
      ],
      "env": {
        "AUTH_ENABLED": "false"
      }
    }
  }
}

🧪 Entwicklung & Tests

Tests ausführen

Das Projekt enthält eine umfassende Testsuite, die Konfiguration, JWT-Überprüfung, Middleware und Tools abdeckt:

uv run pytest -v

Code-Formatierung & Linting

Saubere Codierungsstandards mit ruff durchsetzen:

# Check code
uv run ruff check .

# Auto-fix issues & format
uv run ruff check --fix .
uv run ruff format .

Neue Tools hinzufügen

So fügen Sie ein neues Tool zu livekit-mcp hinzu:

Erstellen Sie ein Modul in src/livekit_mcp/tools/<domain>.py.

Definieren Sie eine Registrierungsfunktion:

from mcp.server.mcpserver import MCPServer

def register_telephony_tools(server: MCPServer) -> None:
    @server.tool(name="trigger_call", description="Trigger an outbound call")
    async def trigger_call(phone_number: str, prompt: str) -> str:
        # Call LktClient here
        return f"Call initiated to {phone_number}"

Registrieren Sie die Funktion in src/livekit_mcp/server.py innerhalb von create_mcp_server().
Fügen Sie Komponententests in tests/test_<domain>.py hinzu.

📚 Agentisches Gedächtnis

Dieses Repository folgt dem Agentic-Memory-Muster. Bevor Sie architektonische Änderungen vornehmen, lesen Sie den Obsidian-Wissensspeicher unter obsidian/:

obsidian/Home.md — Projektnavigations-Hub
obsidian/Architecture/Overview.md — Systemdesign und -topologie
obsidian/Development/Current Sprint.md — Aktueller Entwicklungsstatus
obsidian/Development/TODO.md — Kommende Roadmap
obsidian/Knowledge/Coding Standards.md — Codekonventionen

📄 Lizenz

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

Related MCP Connectors

Hail
io.github.hail-hq
Phone, SMS and email for AI agents. One remote MCP endpoint, OAuth login, zero install.
Communication Email Agent Orchestration
232
https://mcp.hail.so
ClawLink
dev.claw-link
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
App Automation Workplace & Productivity
24
https://claw-link.dev/api/mcp
Bitrix24 B
io.github.bitrix24
MCP server enabling AI agents to manage Bitrix24 features via standardized protocol
ERP Systems Project Management Communication
2
https://mcp.bitrix24.com/mcp/
nexus
com.civic
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Agent Orchestration Developer Tools App Automation
2
https://nexus.civic.com/hub/mcp

Related MCP Servers

@chargebee/mcpofficial
Databases Documentation Access Developer Tools
chargebee
A
license
A
quality
F
maintenance
MCP Server that connects AI agents to Chargebee Platform.
Updated a year ago (2025-11-18 10:04 UTC)
2
60 npm
16
MIT
Agent Identity MCP Server
Security Autonomous Agents
AiAgentKarl
A
license
Not graded
quality
D
maintenance
MCP Server for AI agent identity and authorization. Create, verify, and manage agent identities with trust scores and scoped authorization tokens.
Updated 7 months ago (2026-04-03 16:05 UTC)
27 PyPI
MIT
Smallest MCP Serverofficial
AI & Machine Learning Communication
smallest-inc
A
license
A
quality
A
maintenance
MCP server for the Smallest AI platform that enables managing AI voice agents, debugging calls, and viewing analytics directly from your IDE.
Updated 10 days ago (2026-10-27 06:24 UTC)
84
41 npm
1
MIT
enterprise-auth-mcp-server
Security Developer Tools
AiAgentKarl
A
license
A
quality
D
maintenance
MCP server for enterprise authentication and authorization — JWT validation, OIDC token inspection, OAuth 2.0 introspection, and role-based access control for AI agents.
Updated 7 months ago (2026-04-06 08:37 UTC)
8
MIT

LiveKit MCP Server

📖 Übersicht

Hauptfunktionen

🏛️ Systemarchitektur

📁 Repository-Struktur

🚀 Schnellstart

1. Voraussetzungen

2. Installation & Einrichtung

3. Server ausführen

⚙️ Konfiguration

📡 Endpunkte

Beispiel für den Gesundheitscheck

🔐 Authentifizierung

Anmeldedaten bereitstellen

Erwartete JWT-Ansprüche

🛠️ Verfügbare Tools

1. greet_user

🔌 MCP-Clients verbinden

1. Antigravity / Gemini CLI (~/.gemini/config/mcp_config.json)

2. Cursor IDE (.cursor/mcp.json)

3. Claude Desktop (claude_desktop_config.json)

🧪 Entwicklung & Tests

Tests ausführen

Code-Formatierung & Linting

Neue Tools hinzufügen

📚 Agentisches Gedächtnis

📄 Lizenz

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

@chargebee/mcpofficial

Agent Identity MCP Server

Smallest MCP Serverofficial

enterprise-auth-mcp-server

1. `greet_user`

1. Antigravity / Gemini CLI (`~/.gemini/config/mcp_config.json`)

2. Cursor IDE (`.cursor/mcp.json`)

3. Claude Desktop (`claude_desktop_config.json`)