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
  • 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 SSE MCP Server using Docker

Run the server in Docker (HTTP SSE only)

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

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:

# 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

---

Claude Code CLI

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

{
  "mcpServers": {
    "litmus-mcp-server": {
      "type": "sse",
      "url": "http://localhost:8000/sse",
      "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_USER": "${NATS_USER}",
        "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://<MCP_SERVER_IP>:8000/sse",
      "headers": {
        "EDGE_URL": "https://<LITMUSEDGE_IP>",
        "EDGE_API_CLIENT_ID": "<oauth2_client_id>",
        "EDGE_API_CLIENT_SECRET": "<oauth2_client_secret>",
        "NATS_SOURCE": "<LITMUSEDGE_IP>",
        "NATS_PORT": "4222",
        "NATS_USER": "<access_token_username>",
        "NATS_PASSWORD": "<access_token_from_litmusedge>",
        "INFLUX_HOST": "<LITMUSEDGE_IP>",
        "INFLUX_PORT": "8086",
        "INFLUX_DB_NAME": "tsdata",
        "INFLUX_USERNAME": "<datahub_username>",
        "INFLUX_PASSWORD": "<datahub_password>"
      }
    }
  }
}

Cursor docs

---

VS Code / GitHub Copilot

Manual Configuration

In VS Code: Open User Settings (JSON) → Add:

{
  "mcpServers": {
    "litmus-mcp-server": {
      "url": "http://<MCP_SERVER_IP>:8000/sse",
      "headers": {
        "EDGE_URL": "https://<LITMUSEDGE_IP>",
        "EDGE_API_CLIENT_ID": "<oauth2_client_id>",
        "EDGE_API_CLIENT_SECRET": "<oauth2_client_secret>",
        "NATS_SOURCE": "<LITMUSEDGE_IP>",
        "NATS_PORT": "4222",
        "NATS_USER": "<access_token_username>",
        "NATS_PASSWORD": "<access_token_from_litmusedge>",
        "INFLUX_HOST": "<LITMUSEDGE_IP>",
        "INFLUX_PORT": "8086",
        "INFLUX_DB_NAME": "tsdata",
        "INFLUX_USERNAME": "<datahub_username>",
        "INFLUX_PASSWORD": "<datahub_password>"
      }
    }
  }
}

Or use .vscode/mcp.json in your project.

VS Code MCP Docs

---

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "litmus-mcp-server": {
      "url": "http://<MCP_SERVER_IP>:8000/sse",
      "headers": {
        "EDGE_URL": "https://<LITMUSEDGE_IP>",
        "EDGE_API_CLIENT_ID": "<oauth2_client_id>",
        "EDGE_API_CLIENT_SECRET": "<oauth2_client_secret>",
        "NATS_SOURCE": "<LITMUSEDGE_IP>",
        "NATS_PORT": "4222",
        "NATS_USER": "<access_token_username>",
        "NATS_PASSWORD": "<access_token_from_litmusedge>",
        "INFLUX_HOST": "<LITMUSEDGE_IP>",
        "INFLUX_PORT": "8086",
        "INFLUX_DB_NAME": "tsdata",
        "INFLUX_USERNAME": "<datahub_username>",
        "INFLUX_PASSWORD": "<datahub_password>"
      }
    }
  }
}

Windsurf MCP Docs

STDIO with Claude Desktop

This MCP server supports local connections with Claude Desktop and other applications via Standard file Input/Output (STDIO): https://modelcontextprotocol.io/legacy/concepts/transports

To use STDIO: Clone, edit config.py to enable STDIO, run the server as a local process, and update Claude Desktop MCP server configuration file to use the server:

Clone

# Clone 
git clone https://github.com/litmusautomation/litmus-mcp-server.git

Set ENABLE_STDIO to 'true' in /src/config.py:

ENABLE_STDIO = os.getenv("ENABLE_STDIO", "true").lower() in ("true", "1", "yes")

Run the server

# Run using uv 
uv sync
cd /path/to/litmus-mcp-server
uv run python3 src/server.py

# Otherwise
cd litmus-mcp-server
pip install -e .
python3 src/server.py

Add json server definision to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "litmus-mcp-server": {
      "command": "/path/to/.venv/bin/python3",
      "args": [
        "/absolute/path/to/litmus-mcp-server/src/server.py"
      ],
      "env": {
        "PYTHONPATH": "/absolute/path/to/litmus-mcp-server/src",
        "EDGE_URL": "https://<LITMUSEDGE_IP>",
        "EDGE_API_CLIENT_ID": "<oauth2_client_id>",
        "EDGE_API_CLIENT_SECRET": "<oauth2_client_secret>",
        "NATS_SOURCE": "<LITMUSEDGE_IP>",
        "NATS_PORT": "4222",
        "NATS_USER": "<access_token_username>",
        "NATS_PASSWORD": "<access_token_from_litmusedge>",
        "INFLUX_HOST": "<LITMUSEDGE_IP>",
        "INFLUX_PORT": "8086",
        "INFLUX_DB_NAME": "tsdata",
        "INFLUX_USERNAME": "<datahub_username>",
        "INFLUX_PASSWORD": "<datahub_password>"
      }
    }
  }
}

Tips

For development, use Python Virtual environments, for example to bridge mcp lib version diffs between dev clients like 'npx @modelcontextprotocol/inspector' & litmus-mcp-server

{
  "mcpServers": {
    "litmus-mcp-server": {
      "command": "/absolute/path/to/litmus-mcp-server/.venv/bin/python",
      "args": ["/absolute/path/to/litmus-mcp-server/src/server.py"],
      "env": { /* same as above */ }
    }
  }
}

See claude_desktop_config_venv.example.json for the complete template.

Header Configuration Guide:

• EDGE_URL: Litmus Edge base URL (include https://)
• EDGE_API_CLIENT_ID / EDGE_API_CLIENT_SECRET: OAuth2 credentials from Litmus Edge
• NATS_SOURCE: Litmus Edge IP (no http/https)
• NATS_USER / NATS_PASSWORD: Access token credentials from System → Access Control → Tokens
• INFLUX_HOST: Litmus Edge IP (no http/https)
• INFLUX_USERNAME / INFLUX_PASSWORD: DataHub user credentials

---

Available Tools

40 tools across 8 categories. Tools accept structured arguments and return JSON.

Category	Function Name	Description
DeviceHub — Devices	get_litmusedge_driver_list	List supported Litmus Edge drivers (e.g., ModbusTCP, OPCUA, BACnet).
	get_devicehub_devices	List all configured DeviceHub devices with connection settings and status.
	create_devicehub_device	Create a new device with specified driver and default configuration.
	get_device_connection_status **	Check whether devices are actively publishing data via InfluxDB heartbeat (connected/stale/no_data).
DeviceHub — Tags	get_devicehub_device_tags	Retrieve all tags (data points/registers) for a specific device.
	get_current_value_of_devicehub_tag	Read the current real-time value of a specific device tag.
	create_devicehub_tag	Create a new tag (register) on a device. Driver-required properties auto-fill from defaults.
	update_devicehub_tag	Update mutable fields of an existing tag (display name, description, properties).
	delete_devicehub_tag	Delete a tag from a device. Destructive.
	get_tag_status	Return OK/ERROR status for tags on a specific device. Optionally filter to a single tag.
	get_all_tags_status	Return tag status across all devices. Defaults to non-OK only so issues surface first.
Device Identity	get_litmusedge_friendly_name	Get the human-readable name assigned to the Litmus Edge device.
	set_litmusedge_friendly_name	Update the friendly name of the Litmus Edge device.
LEM Integration	get_cloud_activation_status	Check cloud registration and Litmus Edge Manager (LEM) connection status.
Docker Management	get_all_containers_on_litmusedge	List all Docker containers running on Litmus Edge Marketplace.
	run_docker_container_on_litmusedge	Deploy and run a new Docker container on Litmus Edge Marketplace.
NATS Topics *	get_current_value_from_topic	Subscribe to a NATS topic and return the next published message.
	get_multiple_values_from_topic	Collect multiple sequential values from a NATS topic for trend analysis.
InfluxDB / Time Series **	get_historical_data_from_influxdb	Query historical time-series data from InfluxDB by measurement and time range.
	list_influxdb_measurements	List all measurement names in the tsdata database — discovery for downstream queries.
	get_device_historical_data	Fuzzy-match device names to InfluxDB measurements and pull historical data per match.
	query_tag_data	Query historical data for a specific tag by resolving its output topic. Newest-first.
	get_tag_statistics	Aggregate stats for a tag: mean, min, max, stddev, count, plus baseline range (mean ± 2σ).
	get_device_data_for_inference	Composite payload for AI inference: device metadata, all tags, per-tag stats, and recent samples.
System — Events	get_device_logs	Retrieve system events filtered by time range, component, and severity (INFO/WARN/ALERT/ERROR).
	get_system_event_stats	Event manager statistics: queue sizes, processing rates, memory, health indicators.
System — Network	get_firewall_rules	Return configured firewall rules: ports, protocols, ALLOW/DENY actions.
	get_network_interface_info	Network interface details: IP, MAC, gateway, link status, MTU, speed. Defaults to eth0.
	get_packet_capture_interfaces	List network interfaces available for packet capture.
	get_packet_capture_status	Current packet capture state and list of captured .pcap files with metadata.
	start_packet_capture	Start a packet capture on an interface. Duration 1–30 minutes.
	stop_packet_capture	Stop an in-progress packet capture.
Digital Twins	list_digital_twin_models	List all Digital Twin models with ID, name, description, and version.
	list_digital_twin_instances	List all Digital Twin instances or filter by model ID.
	create_digital_twin_instance	Create a new Digital Twin instance from an existing model.
	list_static_attributes	List static attributes (fixed key-value pairs) for a model or instance.
	list_dynamic_attributes	List dynamic attributes (real-time data points) for a model or instance.
	list_transformations	List data transformation rules configured for a Digital Twin model.
	get_digital_twin_hierarchy	Get the hierarchy configuration for a Digital Twin model.
	save_digital_twin_hierarchy	Save a new hierarchy configuration to a Digital Twin model.

Tool Use Notes

* NATS Topic Tools Requirements: To use get_current_value_from_topic and get_multiple_values_from_topic, you must configure access control on Litmus Edge:

1. Navigate to: Litmus Edge → System → Access Control → Tokens
2. Create or configure an access token with appropriate permissions
3. Provide the token in your MCP client configuration headers

** InfluxDB / Time Series Tools Requirements: To use any tool marked with ** (get_historical_data_from_influxdb, list_influxdb_measurements, get_device_historical_data, query_tag_data, get_tag_statistics, get_device_data_for_inference, get_device_connection_status), you must allow InfluxDB port access:

1. Navigate to: Litmus Edge → System → Network → Firewall
2. Add a firewall rule to allow port 8086 on TCP
3. Ensure InfluxDB is accessible from the MCP server host
4. Provide INFLUX_HOST, INFLUX_PORT, INFLUX_DB_NAME, INFLUX_USERNAME, INFLUX_PASSWORD in your MCP client headers

---

Litmus Central

Download or try Litmus Edge via Litmus Central.

---

MCP server registries

• Glama

• MCP.so

---

© 2026 Litmus Automation, Inc. All rights reserved.