Litmus MCP Server

The official Litmus Automation Model Context Protocol (MCP) Server enables LLMs and intelligent systems to interact with Litmus Edge for device configuration, monitoring, and management. It is built on top of the MCP SDK and adheres to the Model Context Protocol spec.

<div>
<picture>
<source media="(prefers-color-scheme: light)" srcset="static/MCP-server-arch-diagram.png" />

</picture>
</div>

Table of Contents

- Quick Launch
- Web UI
- Persistent Configuration
- Claude Code CLI
- Cursor IDE
- VS Code / Copilot
- Windsurf
- STDIO - Claude Desktop
- Tips
- Tools
- Litmus Central
---

Quick Launch

Start an HTTP MCP Server using Docker

Run the server in Docker (HTTP only)

docker run -d --name litmus-mcp-server -p 8000:8000 ghcr.io/litmusautomation/litmus-mcp-server:latest

The HTTP server exposes both MCP transports on port 8000:

- http://<host>:8000/mcp - Streamable HTTP (current MCP spec, recommended)
- http://<host>:8000/sse - HTTP+SSE (legacy transport, kept for older clients)

Clients that support Streamable HTTP should point at /mcp (e.g. "type": "http", as in the Claude Code example below). The remaining client examples use the SSE endpoint; swap in /mcp if your client supports it, keeping the same headers.

NOTE: The Litmus MCP Server is built for linux/AMD64 platforms. If running in Docker on ARM64, specify the AMD64 platform type by including the --platform argument:

docker run -d --name litmus-mcp-server --platform linux/amd64 -p 8000:8000 ghcr.io/litmusautomation/litmus-mcp-server:main

---

Web UI

The Docker image includes a built-in chat interface that lets you interact with Litmus Edge using natural language — no MCP client configuration required.

Start the server with both ports exposed:

docker run -d --name litmus-mcp-server \
  -p 8000:8000 -p 9000:9000 \
  -e ANTHROPIC_API_KEY=<key> \
  ghcr.io/litmusautomation/litmus-mcp-server:latest

- :9000 — Web UI (chat interface). Open http://localhost:9000 in your browser, add a Litmus Edge instance via the config page, and start chatting.
- :8000 — SSE endpoint for external MCP clients (Claude Desktop, Cursor, VS Code, etc.) — still available as normal.

Supported LLM providers: Anthropic Claude, OpenAI, and Google Gemini. Provide one or more keys at startup (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY) or enter them through the Web UI's setup screen. The active provider and model are switchable from the Web UI's config page at any time.

Multiple Litmus Edge instances: The Web UI lets you register and switch between multiple Litmus Edge devices from a single MCP server. Each instance keeps its own URL and OAuth2 credentials; the active instance's credentials are mirrored into EDGE_URL / EDGE_API_CLIENT_ID / EDGE_API_CLIENT_SECRET automatically. Manage instances under Config → Litmus Edge Instances, or check status per-instance from the Health page.

Live Litmus documentation as MCP Resources: The server exposes litmus://docs/<section> URIs that fetch live content from docs.litmus.io on demand, so MCP-aware clients can pull current reference material directly into the model's context.

If you deploy the MCP server and web client on separate hosts, set MCP_SSE_URL to point the web client at the server:

-e MCP_SSE_URL=http://<mcp-server-host>:8000/sse

Persistent Configuration

By default, configuration saved through the Web UI (API keys, Litmus Edge instances, model preferences, connection settings) is written to .env inside the container and is lost when the container is removed.

To retain configuration across container restarts and replacements, mount a host file over /app/.env:

```bash