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.

Table of Contents

• Quick Launch
  • HTTPS Deployment
  • 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://:8000/mcp` - Streamable HTTP (current MCP spec, recommended)
• `http://: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

HTTPS Deployment

There are two supported ways to serve HTTPS: a TLS-terminating reverse proxy with automatic certificates (recommended when the server has a public hostname), or native TLS with your own certificate files (for private networks with a corporate CA).

Reverse proxy with automatic certificates

The container serves plain HTTP by default and can sit behind a TLS-terminating reverse proxy. `deploy/docker-compose.https.yml` ships that pattern using Caddy, which obtains and renews Let's Encrypt certificates automatically:

# DNS A/AAAA record for mcp.example.com must point at this machine
DOMAIN=mcp.example.com docker compose -f deploy/docker-compose.https.yml up -d

MCP clients then connect to `https://mcp.example.com/mcp` (no port) with the same headers as before. Notes:

• Only Caddy is published to the host (ports 80/443); the MCP server stays on the internal compose network, and the web UI (`:9000`) is deliberately not proxied.
• Certificates persist in the `caddy_data` volume across restarts.
• For private networks without public DNS, uncomment `tls internal` in `deploy/Caddyfile` to use Caddy's internal CA instead (clients must trust that CA).
• Any other TLS-terminating proxy (Traefik, nginx, a cloud load balancer) works the same way: forward to port 8000 and keep SSE responses unbuffered.

Native TLS (bring your own certificate)

When the server runs on a private network without public DNS (so Let's Encrypt cannot issue a certificate), the server can terminate TLS itself using a certificate and key you provide, for example one issued by your corporate CA:

services:
  litmus-mcp-server:
    image: ghcr.io/litmusautomation/litmus-mcp-server:latest
    ports:
      - "8000:8000"
    volumes:
      - /opt/litmus-mcp/certs:/certs:ro
    environment:
      SSL_CERTFILE: /certs/server.crt
      SSL_KEYFILE: /certs/server.key

MCP clients then connect to `https://:8000/mcp`. Notes:

• `SSL_CERTFILE` and `SSL_KEYFILE` are plain environment variables (like `ENABLE_STDIO`), not `.env` settings. Setting only one of them, or pointing at a missing file, aborts startup with an error instead of silently serving plain HTTP.
• `SSL_KEYFILE_PASSWORD` is available for encrypted private keys.
• The certificate must be issued for the hostname clients use, and clients must trust its CA. Self-signed certificates are rejected by claude.ai and Claude Desktop, so use a CA your machines already trust.
• Unlike the Caddy pattern, renewal is manual: replace the files and restart the container before the certificate expires.

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= \
  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.

> Security note: the Web UI is a local operator console. It has no login and it stores LLM API keys and Litmus Edge credentials, so only publish port 9000 on networks you trust; port 8000 (`/mcp`) is the only endpoint intended for MCP clients. Outside Docker, the UI binds to `127.0.0.1` unless you set `WEB_UI_HOST=0.0.0.0` (the Docker image sets this so the `-p 9000:9000` mapping works; simply omit the mapping to keep the UI private). Cross-origin browser access to the UI is disabled unless `WEB_UI_CORS_ORIGINS` is set to a comma-separated list of explicit origins.

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/` 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. Pages are fetched as markdown (a few KB each) rather than rendered HTML (a few hundred KB, mostly navigation), falling back to HTML only where no markdown version is published. `litmus://docs/api` resolves to the API portal's agent router at api.litmus.io/agents.md, and the per-product routers it links to are exposed directly as `litmus://docs/api/edge`, `litmus://docs/api/edgemanager` and `litmus://docs/api/unify`, alongside `litmus://docs/cli` for the litmus-cli guide and `litmus://docs/workflows` for multi-step task recipes. `litmus://docs/api/index` indexes everything the API portal publishes, including per-component pages not served as resources here, and `litmus://docs/reference/message-format` documents the JSON shape the NATS topic tools return.

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://: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`:

# One-time setup — the host file must exist before docker run
mkdir -p /opt/litmus-mcp
touch /opt/litmus-mcp/.env

# Run with the volume mount
docker run -d --name litmus-mcp-server \
  -p 8000:8000 -p 9000:9000 \
  -v /opt/litmus-mcp/.env:/app/.env \
  ghcr.io/litmusautomation/litmus-mcp-server:latest

Any configuration you save in the UI is written to `/opt/litmus-mcp/.env` on the host. A new container started with the same `-v` flag will pick it up automatically on startup.

> Note: The host-side file must be created with `touch` before running the container. If it does not exist, Docker creates a directory at that path and the application will fail to write configuration.

Docker Compose equivalent:

services:
  litmus-mcp-server:
    image: ghcr.io/litmusautomation/litmus-mcp-server:latest
    ports:
      - "8000:8000"
      - "9000:9000"
    volumes:
      - /opt/litmus-mcp/.env:/app/.env

> Note: `NATS_SOURCE`, `NATS_PORT`, `INFLUX_HOST`, and `INFLUX_PORT` are optional in all of the client configurations below. When omitted, the server derives the hosts from `EDGE_URL` (defaulting to `nats://:4222` and `http://:8086`) and mentions the fallback in tool responses. Set them only when the data plane is reachable at a different address or port than the Edge web UI.

Claude Code CLI

Run Claude from a directory that includes a configuration file at `~/.claude/mcp.json`:

{
  "mcpServers": {
    "litmus-mcp-server": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "EDGE_URL": "${EDGE_URL}",
        "EDGE_API_CLIENT_ID": "${EDGE_API_CLIENT_ID}",
        "EDGE_API_CLIENT_SECRET": "${EDGE_API_CLIENT_SECRET}",
        "NATS_SOURCE": "${NATS_SOURCE}",
        "NATS_PORT": "${NATS_PORT:-4222}",
        "NATS_PASSWORD": "${NATS_PASSWORD}",
        "INFLUX_HOST": "${INFLUX_HOST}",
        "INFLUX_PORT": "${INFLUX_PORT:-8086}",
        "INFLUX_DB_NAME": "${INFLUX_DB_NAME:-tsdata}",
        "INFLUX_USERNAME": "${INFLUX_USERNAME}",
        "INFLUX_PASSWORD": "${INFLUX_PASSWORD}"
      }
    }
  }
}

Anthropic Docs

Cursor IDE

Add to `~/.cursor/mcp.json` or `.cursor/mcp.json`:

{
  "mcpServers": {
    "litmus-mcp-server": {
      "url": "http://:8000/sse",
      "headers": {
        "EDGE_URL": "https://",
        "EDGE_API_CLIENT_ID": "",
        "EDGE_API_CLIENT_SECRET": "",
        "NATS_SOURCE": "",
        "NATS_PORT": "4222",
        "NATS_PASSWORD": "

- [MCP.so](https://mcp.so/server/litmus-mcp-server/litmusautomation)

---

© 2026 Litmus Automation, Inc. All rights reserved.