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

Высокопроизводительный сервер Model Context Protocol (MCP 2.0), связывающий ИИ-агентов с движком MantraCare LiveKit Voice & Telephony Engine.

Архитектура • Быстрый старт • Конфигурация • Подключение клиентов • Аутентификация • Инструменты • Разработка

📖 Обзор

LiveKit MCP Server позволяет LLM и ИИ-ассистентам по коду (таким как Antigravity, Claude, Cursor и пользовательские агенты) безопасно управлять, проверять и запускать конвейеры голосовой телефонии, работающие на базе LiveKit (~/lkt) и аутентифицированные через Mantra Auth (~/mantra-auth).

Ключевые возможности

🚀 Соответствие MCP 2.0: построен на официальном Python mcp SDK с использованием Server-Sent Events (SSE) и Streamable HTTP транспорта.
🔐 OAuth 2.1 и общая безопасность JWT: нативная проверка HS256 JWT, совместимая с mantra-auth, с поддержкой заголовка Authorization: Bearer и параметра запроса ?token=.
⚡ Молниеносное асинхронное ядро: на базе Starlette, Uvicorn и менеджера пакетов uv.
🧩 Модульная архитектура инструментов: раздельные по доменам инструменты для телефонии, аналитики звонков, поиска по базе знаний и SIP-транкинга.
🧠 Агентная память: полная база знаний Obsidian (obsidian/) и правила AGENTS.md для сохранения контекста парного программирования с ИИ.

Related MCP server: Agent Identity MCP Server

🏛️ Системная архитектура

┌─────────────────────────────────────────────────────────────┐
│ 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)  │
└─────────────────────────────────────────────────────────────┘

📁 Структура репозитория

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

🚀 Быстрый старт

1. Предварительные требования

Python: 3.11 и выше
uv: быстрый менеджер пакетов Python (Установить uv)
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```

2. Установка и настройка

Склонируйте репозиторий и перейдите в каталог:
```
cd ~/livekit-mcp
```
Создайте файл конфигурации окружения:
```
cp .env.example .env
```
Установите зависимости с помощью uv:
```
uv sync
```

3. Запуск сервера

Запустите сервер разработки с автоматической перезагрузкой:

./dev.sh

Или запустите напрямую с помощью uv:

uv run python -m livekit_mcp.main

Сервер будет доступен по адресу http://localhost:8000.

⚙️ Конфигурация

Все параметры задаются в src/livekit_mcp/config.py через pydantic-settings и загружаются из .env:

Переменная	Тип	По умолчанию	Описание
`HOST`	string	`0.0.0.0`	Адрес привязки сервера
`PORT`	integer	`8000`	Порт прослушивания сервера
`ENVIRONMENT`	string	`development`	`development`, `test` или `production`
`LOG_LEVEL`	string	`INFO`	Уровень журналирования (`DEBUG`, `INFO`, `WARNING`, `ERROR`)
`AUTH_ENABLED`	boolean	`true`	Требовать JWT-аутентификацию для защищённых конечных точек
`JWT_SECRET`	string	`your-super-secret-...`	Общий секретный ключ для проверки подписи HS256 JWT
`JWT_ALGORITHM`	string	`HS256`	Алгоритм подписи JWT (совпадает с `mantra-auth`)
`AUTH_SERVER_URL`	string	`http://localhost:3000`	Базовый URL сервера Mantra Auth
`JWT_ISSUER`	string	`http://localhost:3000`	Ожидаемый эмитент JWT (`iss`)
`JWT_AUDIENCE`	string	(пусто)	Необязательная ожидаемая аудитория (`aud`)
`LKT_API_BASE_URL`	string	`http://localhost:8081`	Базовый URL API голосового агента LKT
`LKT_API_TIMEOUT`	float	`15.0`	Тайм-аут HTTP-запросов в секундах для вызовов LKT
`LIVEKIT_URL`	string	(пусто)	Прямой WebSocket URL LiveKit Cloud (необязательно)
`LIVEKIT_API_KEY`	string	(пусто)	Прямой API-ключ LiveKit Cloud (необязательно)
`LIVEKIT_API_SECRET`	string	(пусто)	Прямой секрет API LiveKit Cloud (необязательно)

📡 Конечные точки

Конечная точка	Метод	Требуется аутентификация	Описание
`/health`	`GET`	❌ Нет	Публичная проверка работоспособности и готовности сервиса
`/`	`GET`	❌ Нет	Статус сервиса и метаданные конечных точек
`/sse`	`GET`	✅ Да	Открывает постоянный поток Server-Sent Events (SSE) для MCP-клиентов
`/messages`	`POST`	✅ Да	Конечная точка JSON-RPC 2.0 для MCP-запросов (выполнение инструментов, перечисление)

Пример проверки работоспособности

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"
}

🔐 Аутентификация

Сервер реализует OAuth 2.1 / HS256 JWT-аутентификацию с общим секретом, совместимую с mantra-auth.

Предоставление учётных данных

Заголовок Authorization (стандартный):

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

Параметр запроса (для SSE / EventSource-клиентов):
```
GET /sse?token=<your-jwt-access-token> HTTP/1.1
Host: localhost:8000
```

Ожидаемые утверждения JWT

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

Совет разработчику: установите AUTH_ENABLED=false в .env, чтобы отключить проверку токенов при локальном тестировании.

🛠️ Доступные инструменты

1. `greet_user`

Проверочный инструмент, который проверяет связность MCP, разбор параметров и статус сервера.

Параметры:
- name (string, required): имя пользователя или агента, вызывающего инструмент.
- message (string, optional): пользовательское приветственное сообщение.

Возвращает:

👋 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-клиентов

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"
      }
    }
  }
}

🧪 Разработка и тестирование

Запуск тестов

Проект содержит полный набор тестов, покрывающий конфигурацию, проверку JWT, middleware и инструменты:

uv run pytest -v

Форматирование кода и линтер

Обеспечьте чистые стандарты кода с помощью ruff:

# Check code
uv run ruff check .

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

Добавление новых инструментов

Чтобы добавить новый инструмент в livekit-mcp:

Создайте модуль в src/livekit_mcp/tools/<domain>.py.

Определите функцию регистрации:

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}"

Зарегистрируйте функцию в src/livekit_mcp/server.py внутри create_mcp_server().
Добавьте модульные тесты в tests/test_<domain>.py.

📚 Агентная память

Этот репозиторий следует паттерну агентной памяти. Перед внесением архитектурных изменений ознакомьтесь с базой знаний Obsidian в obsidian/:

obsidian/Home.md — навигационный центр проекта
obsidian/Architecture/Overview.md — архитектура системы и топология
obsidian/Development/Current Sprint.md — статус текущего спринта
obsidian/Development/TODO.md — ближайший план работ
obsidian/Knowledge/Coding Standards.md — конвенции по стилю кода

📄 Лицензия

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

ResponsivenessNo issues

Resources

Related MCP Connectors

HailOAuth
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
ClawLinkOAuth
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 BOAuth
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/
nexusOAuth
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
69 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)
43 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 6 days ago (2026-10-27 06:24 UTC)
84
33 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

📖 Обзор

Ключевые возможности

🏛️ Системная архитектура

📁 Структура репозитория

🚀 Быстрый старт

1. Предварительные требования

2. Установка и настройка

3. Запуск сервера

⚙️ Конфигурация

📡 Конечные точки

Пример проверки работоспособности

🔐 Аутентификация

Предоставление учётных данных

Ожидаемые утверждения JWT

🛠️ Доступные инструменты

1. greet_user

🔌 Подключение MCP-клиентов

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

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

3. Claude Desktop (claude_desktop_config.json)

🧪 Разработка и тестирование

Запуск тестов

Форматирование кода и линтер

Добавление новых инструментов

📚 Агентная память

📄 Лицензия

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`)