Skip to main content
Glama
Sign In
deenesjakoruzh
LiveKit MCP Server

LiveKit MCP Server

by Mantracare-Org
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

LiveKit MCP サーバー

Python uv MCP Code style: ruff Tests

AIエージェントとMantraCare LiveKit Voice & Telephony Engineを橋渡しする、高性能なModel Context Protocol（MCP 2.0）サーバーです。

アーキテクチャ • クイックスタート • 設定 • クライアントの接続 • 認証 • ツール • 開発

📖 概要

LiveKit MCP Server は、LLMやAIコーディングアシスタント（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 セキュリティ: mantra-auth に一致するネイティブなHS256 JWT検証。Authorization: Bearer ヘッダーと ?token= クエリパラメータの両方をサポート。

  • ⚡ 超高速非同期コア: Starlette、Uvicorn、uv パッケージ管理を採用。

  • 🧩 モジュール式ツールアーキテクチャ: テレフォニー、通話分析、ナレッジベース検索、SIPトランキング用にドメイン分離されたツール。

  • 🧠 エージェントメモリ: 完全な Obsidian ナレッジベース(obsidian/)と AGENTS.md ルールにより、AIペアプログラミングのコンテキストを保持します。

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. インストールとセットアップ

  1. リポジトリをクローンしてディレクトリに入ります：

    cd ~/livekit-mcp

  2. 環境設定ファイルを作成します：

    cp .env.example .env

  3. 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

Mantra Auth サーバーのベースURL

JWT_ISSUER

string

http://localhost:3000

期待されるJWT発行者クレーム（iss）

JWT_AUDIENCE

string

(空)

期待されるオーディエンスクレーム（aud）

LKT_API_BASE_URL

string

http://localhost:8080

LKT Voice Agent API のベースURL

LKT_API_TIMEOUT

float

15.0

LKT API へのHTTPリクエストのタイムアウト（秒）

LIVEKIT_URL

string

(空)

LiveKit Cloud の WebSocket URL

LIVEKIT_API_KEY

string

(空)

LiveKit Cloud API キー

LIVEKIT_API_SECRET

string

(空)

LiveKit Cloud API シークレット

📡 エンドポイント

エンドポイント

メソッド

認証必須

説明

/health

GET

❌ いいえ

サービスステータスと依存関係の健全性を確認する公開エンドポイント

/

GET

❌ いいえ

サービス情報と設定

/messages

POST

✅ はい

MCP ツール呼び出しのための JSON-RPC エンドポイント

/mcp

GET

✅ はい

MCP のStreamable HTTPトランスポートエンドポイント

ヘルスチェック例

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

🔐 認証

サーバーは、mantra-auth と互換性のある OAuth 2.1 & 共有 JWT 認証 を実装しています。

認証情報の提供

  1. Authorization ヘッダー（標準）:

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

  2. クエリパラメータ（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"
}

開発時のヒント: ローカルテスト中は、.env 内で AUTH_ENABLED=false に設定するとトークン検証を無効化できます。

🛠️ 利用可能なツール

1. greet_user

認証、パラメータ解析、サーバー状態を検証するためのシンプルなテストツールです。

  • パラメータ:

    • name (文字列, 必須): ツールを呼び出すユーザーまたはエージェントの名前。

    • message (文字列, 任意): カスタム挨拶メッセージ。

  • 戻り値:

    👋 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.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検証、ミドルウェア、ツールをカバーする包括的なテストスイートが含まれています:

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 に追加するには:

  1. src/livekit_mcp/tools/<domain>.py にモジュールを作成します。

  2. モジュール内でツールを定義します:

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

  3. create_mcp_server() 内の src/livekit_mcp/server.py に関数を登録します。

📚 ナレッジベース

このプロジェクトは、AI ペアプログラミングのコンテキストを提供するために、AGENTS.md ファイルと完全な Obsidian ナレッジベース (obsidian/) を維持しています:

  • obsidian/Home.md — プロジェクトのホーム

  • obsidian/Architecture.md — システムアーキテクチャのドキュメント

  • obsidian/Development.md — 開発プロセスとガイドライン

  • obsidian/Knowledge.md — ドメイン知識とベストプラクティス

📄 ライセンス

Proprietary © MantraCare. 無断複写・転載を禁じます。

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

Related MCP Servers