What can you do with this server?

The livekit-agent-simulator server lets you simulate AI caller interactions against a LiveKit voice agent, record detailed behavioral logs, and analyze/compare results — without touching the agent's code. * init_project — Scaffold a .agent-sim/ directory (config + smoke scenario) in your target repo and add it to .gitignore. * list_scenarios — List all available scenarios (from .agent-sim/scenarios/*.jsonl) with their IDs, tags, and validity status. * validate_scenario — Validate a scenario file against its schema, checking for a required Persona brief and linting the PassCriteria. * export_scenario — Export a parsed scenario's full details (Persona, execution parameters, PassCriteria) as JSON. * run_scenario / execute_scenario — Run a simulation for a given scenario (the latter validates first), returning a run_id for tracking. * execute_scenarios — Execute multiple scenarios at once, optionally filtered by tag (e.g. smoke) or specific IDs. * get_run_status — Poll a simulation run's current state (running / done / failed), turn count, and duration. * get_run_log — Read the raw events.jsonl log for a run, with filtering by event kind (supports wildcards like tool.*), turn number, source, and time offset. * get_run_report — Retrieve a full report including summary, LLM judge verdict, suspicious turns, and paths to timeline/event files. * compare_runs — Diff two simulation runs side-by-side across duration, turn counts, tool errors, turn-taking percentiles, and judge verdicts. * list_runs — Browse run history (newest first) from SQLite, optionally filtered by scenario ID. All tools operate on a project_root (the repo under test) and assume the target agent is already deployed.

How do I use livekit-agent-simulator?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@livekit-agent-simulator run the smoke-hello scenario" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

livekit-agent-simulator

by quangdang46

Overview Schema Related Servers Score Discussions

Python

Local

livekit-agent-simulator

Standalone MCP server + CLI (lk-sim) that dials any LiveKit voice agent with an AI simulated caller (Gemini Live) and records a full forensic behavior log — transcripts, tool events, flow events, room events — all timestamped per turn.

Zero-touch: the agent under test is a black box. The simulator only needs the agent's registered agent_name; it never reads or modifies the target project's code, .env, or model config.

CLI and MCP expose the same public ops (shared ops.py). No duplicate “run vs execute” paths — use execute_* to validate then run.

How it works

Reads <your-repo>/.agent-sim/config.yaml (LiveKit creds + agent_name + simulator voice).
Creates a fresh room lk-sim-<run-id> and dispatches the agent via RoomAgentDispatch.
Joins as participant lk-sim-caller, bridges audio with a Gemini Live session (gemini-3.1-flash-live-preview) playing the scenario persona.
Observes everything from inside the room: lk.transcription text streams, custom data topics (when configured), audio timing, interruptions, silences.
Writes reports/<run-id>/ — events.jsonl, timeline.md, summary.json, meta.json, optional conversation.wav — and mirrors to runs.sqlite.
Optional LLM judge (gemini-2.5-flash) scores the transcript + tool spans against the scenario's PassCriteria.

Related MCP server: PhoneBooth MCP Server

Install (user machine)

Download only — no uv/pip/build on your machine. CI ships a portable pack (embedded Python + deps + report player). The installer unzips it and adds lk-sim to PATH.

# macOS / Linux (from release asset — preferred)
curl -fsSL "https://github.com/quangdang46/livekit-agent-simulator/releases/download/v0.1.0/install.sh" | bash -s -- --verify

# Windows PowerShell (from release asset — preferred)
irm "https://github.com/quangdang46/livekit-agent-simulator/releases/download/v0.1.0/install.ps1" -OutFile "$env:TEMP\lk-sim-install.ps1"
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP\lk-sim-install.ps1" -Verify

Then:

lk-sim guide
lk-sim web --root /path/to/target   # no Node — report player is prebuilt into the package

Installer options:

curl -fsSL "https://github.com/quangdang46/livekit-agent-simulator/releases/download/v0.1.0/install.sh" | bash -s -- --ref v0.1.0 --verify
curl -fsSL "https://github.com/quangdang46/livekit-agent-simulator/releases/download/v0.1.0/install.sh" | bash -s -- --no-mcp
curl -fsSL "https://github.com/quangdang46/livekit-agent-simulator/releases/download/v0.1.0/install.sh" | bash -s -- --uninstall

.\install.ps1 -GitRef v0.1.0 -Verify
.\install.ps1 -NoMcp
.\install.ps1 -Uninstall

By default the installer also registers the MCP server livekit-agent-simulator as lk-sim mcp into common AI coding tools (Claude Code, Cursor, Cline, Windsurf, VS Code Copilot, Gemini CLI, Amazon Q, OpenCode, Codex, Warp when present).

Report player (maintainers)

Source: web/ (Vite + TypeScript). Users never run this — CI builds into the portable pack / wheel.

pnpm --dir web install
pnpm --dir web build    # → templates/report-player/ (served by lk-sim web)
pnpm --dir web dev      # HMR; proxy /api + /runs → lk-sim web on :8765

Release (maintainers)

# after main is green:
git tag -f v0.1.0 && git push origin main && git push origin v0.1.0 --force
# → GitHub Actions:
#    wheel + portable packs (windows-x64, linux-x64, macos-arm64, macos-x64)
#    assets: install.sh + install.ps1 + lk-sim-*.zip + *.whl
# Keep single version 0.1.0 while pre-1.0 (force-retag).

Quick start

# In the repo you want to test (agent worker must be running; set `agent_name` in config):
lk-sim init --root /path/to/target
#   → scaffolds .agent-sim/ (gitignored) — fill in config.yaml

lk-sim preflight --root /path/to/target
lk-sim execute smoke-hello --root /path/to/target
lk-sim report <run-id> --root /path/to/target
lk-sim web --root /path/to/target          # audio + transcript player (Ctrl+C to stop)

MCP (after install)

Installer writes the MCP command when tools are detected. Manual Cursor example:

{
  "mcpServers": {
    "livekit-agent-simulator": {
      "command": "lk-sim",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Equivalent one-shot entry: lk-sim-mcp (same process as lk-sim mcp).

Dev checkout (package not installed globally):

{
  "mcpServers": {
    "livekit-agent-simulator": {
      "command": "uv",
      "args": ["run", "--directory", "/abs/path/livekit-agent-simulator", "lk-sim", "mcp"]
    }
  }
}

Public ops (CLI ↔ MCP)

CLI	MCP tool	Purpose
`init`	`init_project`	Scaffold `.agent-sim/` + gitignore
`guide`	`guide`	On-demand setup/ops guide (markdown)
`web`	`web`	Local report player (audio + transcript sync)
`preflight`	`preflight`	Config + LiveKit connectivity
`scenarios`	`list_scenarios`	List `scenarios/*.jsonl`
`plugins`	`list_plugins`	Verify plugins
`validate`	`validate_scenario`	Schema + lint
`export`	`export_scenario`	Parsed scenario JSON
`scenario-init`	`init_scenario`	Scaffold `.jsonl` with `//` guides + examples
`execute`	`execute_scenario`	Validate then run one JSONL scenario
`execute-all`	`execute_scenarios`	Batch (optional ids / tag)
`execute-dict`	`execute_scenario_dict`	Validate then run in-memory dict
`status`	`get_run_status`	SQLite run status
`log`	`get_run_log`	Filtered `events.jsonl`
`report`	`get_run_report`	Summary + verdict + audio path
`compare`	`compare_runs`	Diff two runs
`runs`	`list_runs`	Run history

Docs

AGENTS.md — rules for AI agents (research loop, package boundary)
docs/smoke-test.md — first end-to-end run
docs/portability.md — consumer-specific dispatch / observe setup
docs/plugins.md — verify plugins + Python API

CI / Release

Workflow	Trigger	What it does
CI	PR / push → `main`	pnpm report-player build, `pytest` (3.10 + 3.12), `lk-sim --help`
Release	tag `v*`	pytest → wheel → portable packs (win/linux/mac) → GitHub Release

Local check:

uv sync --extra dev
pnpm --dir web build
uv run pytest -q

Release:

git tag v0.1.0
git push origin v0.1.0

Install Server

license - permissive license

quality

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

1Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Tools

View all tools

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

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/quangdang46/livekit-agent-simulator'

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