Skip to main content
Glama
Sign In
deenesjakoruzh
LiveKit MCP Server

LiveKit MCP Server

by Mantracare-Org
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

LiveKit MCP Server

Python uv MCP Code style: ruff [![Tests](https://img.shields.io/badge/tests-18%20passed-

AI 에이전트와 MantraCare LiveKit 음성·전화 엔진을 연결하는 고성능 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를 기반으로 SSE(Server-Sent Events) 및 Streamable HTTP 전송을 사용합니다.

  • 🔐 OAuth 2.1 및 공유 JWT 보안: mantra-auth와 일치하는 네이티브 HS256 JWT 검증을 지원하며, Authorization: Bearer 헤더와 ?token= 쿼리 매개변수를 모두 지원합니다.

  • ⚡ 초고속 비동기 코어: Starlette, Uvicorn 및 uv 패키지 관리로 구동됩니다.

  • 🧩 모듈식 도구 아키텍처: 전화, 통화 분석, 지식 베이스 검색, SIP 트렁킹을 위한 도메인별 도구를 제공합니다.

  • 🧠 에이전트 메모리: AI 페어 프로그래밍 컨텍스트 보존을 위한 전체 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. 설치 및 설정

  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 에서 사용할 수 있습니다.

⚙️ 구성

모든 설정은 pydantic-settings을 사용하여 src/livekit_mcp/config.py에서 관리하며, .env에서 로드됩니다:

변수

유형

기본값

설명

HOST

문자열

0.0.0.0

서버 바인딩 주소

PORT

정수

8000

서버 수신 대기 포트

ENVIRONMENT

문자열

development

development, test 또는 production

LOG_LEVEL

문자열

INFO

로깅 수준 (DEBUG, INFO, WARNING, ERROR)

AUTH_ENABLED

불리언

true

보호된 엔드포인트에 대한 JWT 인증 강제 여부

JWT_SECRET

문자열

your-super-secret-...

HS256 JWT 서명 검증을 위한 공유 비밀 키

JWT_ALGORITHM

문자열

HS256

JWT 서명 알고리즘 (mantra-auth와 일치)

AUTH_SERVER_URL

문자열

http://localhost:3000

Mantra Auth 서버의 기본 URL

JWT_ISSUER

문자열

http://localhost:3000

예상 JWT 발행자 클레임 (iss)

JWT_AUDIENCE

문자열

(비어 있음)

선택적인 예상 대상 클레임 (aud)

LKT_API_BASE_URL

문자열

http://localhost:8081

LKT Voice Agent API의 기본 URL

LKT_API_TIMEOUT

실수

15.0

LKT 호출에 대한 HTTP 요청 타임아웃(초)

LIVEKIT_URL

문자열

(비어 있음)

직접 연결하는 LiveKit Cloud WebSocket URL (선택 사항)

LIVEKIT_API_KEY

문자열

(비어 있음)

직접 연결하는 LiveKit Cloud API 키 (선택 사항)

LIVEKIT_API_SECRET

문자열

(비어 있음)

직접 연결하는 LiveKit Cloud API 비밀 키 (선택 사항)

📡 엔드포인트

엔드포인트

메서드

인증 필요

설명

/health

GET

❌ 아니요

서비스 상태를 반환하는 공개 Health / 준비 상태 확인

/

GET

❌ 아니요

서비스 상태 및 엔드포인트 메타데이터

/sse

GET

✅ 예

MCP 클라이언트를 위한 지속적인 SSE(Server-Sent Events) 스트림 열기

/messages

POST

✅ 예

MCP 요청(도구 실행, 목록 조회)을 위한 JSON-RPC 2.0 엔드포인트

Health Check 예시

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 / HS256 공유 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

MCP 연결, 매개변수 파싱 및 서버 상태를 검증하는 확인용 도구입니다.

  • 매개변수:

    • name (string, 필수): 도구를 호출하는 사용자 또는 에이전트의 이름.

    • message (string, 선택 사항): 사용자 지정 인사말 메시지.

  • 반환 값:

    👋 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 검증, 미들웨어 및 도구를 다루는 포괄적인 테스트 스위트가 포함되어 있습니다:

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. src/livekit_mcp/server.py의 create_mcp_server() 안에서 해당 함수를 등록합니다.

  4. 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 — 코드 규칙

📄 라이선스

독점 라이선스 © MantraCare. All rights reserved.

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

Related MCP Servers