Skip to main content
Glama
deenesjakoruzh
FardeenSK004

LiveKit MCP Server

by FardeenSK004
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

LiveKit MCP Server

Python uv MCP Code style: ruff Tests

A high-performance Model Context Protocol (MCP 2.0) Server bridging AI Agents with the MantraCare LiveKit Voice & Telephony Engine.

Architecture • Quick Start • Configuration • Connecting Clients • Authentication • Tools • Development

📖 Overview

The LiveKit MCP Server allows LLMs and AI coding assistants (such as Antigravity, Claude, Cursor, and custom agents) to securely control, inspect, and trigger voice telephony pipelines powered by LiveKit (~/lkt) and authenticated via Mantra Auth (~/mantra-auth).

Key Capabilities

  • 🚀 MCP 2.0 Compliance: Built on the official Python mcp SDK using Server-Sent Events (SSE) and Streamable HTTP transports.

  • 🔐 OAuth 2.1 & Shared JWT Security: Native HS256 JWT validation matching mantra-auth, with support for both Authorization: Bearer headers and ?token= query parameters.

  • ⚡ Lightning Fast Async Core: Powered by Starlette, Uvicorn, and uv package management.

  • 🧩 Modular Tool Architecture: Domain-separated tools for telephony, call analytics, knowledge base search, and SIP trunking.

  • 🧠 Agentic Memory: Full Obsidian knowledge base (obsidian/) and AGENTS.md rules for AI pair programming context preservation.

Related MCP server: Agent Identity MCP Server

🏛️ System Architecture

┌─────────────────────────────────────────────────────────────┐
│ 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 Layout

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

🚀 Quick Start

1. Prerequisites

  • Python: 3.11 or higher

  • uv: Fast Python package manager (Install uv)

    curl -LsSf https://astral.sh/uv/install.sh | sh

2. Installation & Setup

  1. Clone the repository and enter the directory:

    cd ~/livekit-mcp

  2. Create your environment configuration:

    cp .env.example .env

  3. Install dependencies with uv:

    uv sync

3. Running the Server

Start the development server with auto-reload:

./dev.sh

Or run directly using uv:

uv run python -m livekit_mcp.main

The server will be available at http://localhost:8000.

⚙️ Configuration

All settings are managed in src/livekit_mcp/config.py using pydantic-settings and loaded from .env:

Variable

Type

Default

Description

HOST

string

0.0.0.0

Server bind address

PORT

integer

8000

Server listening port

ENVIRONMENT

string

development

development, test, or production

LOG_LEVEL

string

INFO

Logging level (DEBUG, INFO, WARNING, ERROR)

AUTH_ENABLED

boolean

true

Enforce JWT authentication on protected endpoints

JWT_SECRET

string

your-super-secret-...

Shared secret key for HS256 JWT signature verification

JWT_ALGORITHM

string

HS256

JWT signing algorithm (matches mantra-auth)

AUTH_SERVER_URL

string

http://localhost:3000

Base URL of the Mantra Auth server

JWT_ISSUER

string

http://localhost:3000

Expected JWT issuer claim (iss)

JWT_AUDIENCE

string

(empty)

Optional expected audience claim (aud)

LKT_API_BASE_URL

string

http://localhost:8081

Base URL of the LKT Voice Agent API

LKT_API_TIMEOUT

float

15.0

HTTP request timeout in seconds for LKT calls

LIVEKIT_URL

string

(empty)

Direct LiveKit Cloud WebSocket URL (optional)

LIVEKIT_API_KEY

string

(empty)

Direct LiveKit Cloud API Key (optional)

LIVEKIT_API_SECRET

string

(empty)

Direct LiveKit Cloud API Secret (optional)

📡 Endpoints

Endpoint

Method

Auth Required

Description

/health

GET

❌ No

Public health & readiness check returning service status

/

GET

❌ No

Service status and endpoint metadata

/sse

GET

✅ Yes

Opens a persistent Server-Sent Events (SSE) stream for MCP clients

/messages

POST

✅ Yes

JSON-RPC 2.0 endpoint for MCP requests (tool execution, listings)

Health Check Sample

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

🔐 Authentication

The server implements OAuth 2.1 / HS256 Shared JWT Authentication compatible with mantra-auth.

Supplying Credentials

  1. Authorization Header (Standard):

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

  2. Query Parameter (For SSE / EventSource clients):

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

Expected JWT Claims

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

Development Tip: Set AUTH_ENABLED=false in .env to disable token verification during local testing.

🛠️ Available Tools

1. greet_user

A verification tool that validates MCP connectivity, parameter parsing, and server status.

  • Parameters:

    • name (string, required): Name of the user or agent invoking the tool.

    • message (string, optional): Custom greeting message.

  • Returns:

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

🔌 Connecting MCP Clients

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

🧪 Development & Testing

Running Tests

The project includes a comprehensive test suite covering configuration, JWT verification, middleware, and tools:

uv run pytest -v

Code Formatting & Linting

Enforce clean coding standards using ruff:

# Check code
uv run ruff check .

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

Adding New Tools

To add a new tool to livekit-mcp:

  1. Create a module in src/livekit_mcp/tools/<domain>.py.

  2. Define a registration function:

    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. Register the function in src/livekit_mcp/server.py inside create_mcp_server().

  4. Add unit tests in tests/test_<domain>.py.

📚 Agentic Memory

This repository adheres to the Agentic Memory pattern. Before making architectural changes, review the Obsidian knowledge vault at obsidian/:

  • obsidian/Home.md — Project navigation hub

  • obsidian/Architecture/Overview.md — System design & topology

  • obsidian/Development/Current Sprint.md — Active development status

  • obsidian/Development/TODO.md — Upcoming roadmap

  • obsidian/Knowledge/Coding Standards.md — Code conventions

📄 License

Proprietary © MantraCare. All rights reserved.

This server cannot be installed

F
license - not found
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • Hail

    Phone, SMS & email for AI agents — one remote MCP endpoint, OAuth login, zero install.

  • secureflows-mcp-server

    MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.

  • pAIchart MCP Hub

    MCP Hub: AI service discovery, per-user OAuth, and multi-service workflow orchestration

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/FardeenSK004/livekit-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server