Litmus Mcp Server
About
Enables LLMs and intelligent systems to interact with Litmus Edge for device configuration, monitoring, and management.
Details
- License
- Apache-2.0
Explore
- Dockerized HTTP/SSE MCP server with Web UI
- Built‑in chat interface for natural language interaction
- Multiple LLM provider support: Anthropic, OpenAI, Google Gemini
- Persistent configuration via host‑mounted .env file
- Live Litmus documentation served as MCP Resources
- Manage multiple Litmus Edge instances from a single server
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Litmus Mcp ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
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:
mkdir -p /opt/litmus-mcp
touch /opt/litmus-mcp/.env
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.
---
ENABLE_STDIO = os.getenv("ENABLE_STDIO", "true").lower() in ("true", "1", "yes")
- 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>"
}
}
}
}
```
Category
Function Name
59 tools across 12 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. |
| Cloud / LEM Activation| 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 sigma). |
| | get_device_data_for_inference | Composite payload for AI inference: device metadata, all tags, per-tag stats, and recent samples. |
| System, Events | get_system_events | 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. |
| | create_digital_twin_model | Create a new Digital Twin model. |
| | 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. |
| Litmus Edge Manager (LEM) | lem_list_devices | List edge devices registered in a LEM project (paginated). |
| | lem_get_device_details | Full LEM-side record for a single edge device (versions, license, last seen, config). |
| | lem_list_device_versions | List Litmus Edge versions registered in a LEM project. |
| | lem_list_device_groups | List device group labels (project-level groupings) defined in a LEM project. |
| | lem_get_license_expiry | List devices whose license expires within the next N days. |
| | lem_get_expired_licenses | List devices in a LEM project whose license has already expired. |
| | lem_dashboard_usage | Project usage summary (device counts, license usage, deployment stats). |
| | lem_get_project_alerts | List active project-level alerts (device offline, license issues, etc.). |
| | lem_list_companies | List all companies on the LEM tenant with project/device/model counts. |
| | lem_get_company_details | Full details for a single company by name (teams, license, quotas). |
| | lem_list_company_projects | List all projects belonging to a given company. |
| | lem_get_project_details | Single-project details (timezone, data TTL, allocated slots, billing plan). |
| | lem_deployment_info | LEM tenant deployment info (version, build, release metadata). |
| | lem_get_system_time | LEM server clock; useful when comparing edge timestamps. |
| LEM Bridge | lem_bridge_list_devicehub_devices | List devicehub devices on a specific edge by tunneling through LEM (no active-instance switch). |
| | lem_bridge_get_le_info | Identity info (friendly name, cloud activation) for an edge via the LEM bridge. |
| SDK Fallback (CLI) *| litmus_sdk_discover | Browse the full generated SDK catalog (~550 functions) by dotted-path prefix. |
| | litmus_sdk_call | Invoke any SDK function by dotted path. Approval-gated; potentially destructive. |
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"litmus mcp server": {
"litmus-mcp-server": {
"url": "http://<IP Address>:8000/sse"
}
}
}
}McpServers
{
"litmus-mcp-server": {
"url": "http://<IP Address>:8000/sse"
}
}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
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
