litmus-mcp-server

<p align="center"> <a href="https://litmus.io"> <picture> <source media="(prefers-color-scheme: light)" srcset="static/litmus-logo-light.svg" /> <source media="(prefers-color-scheme: dark)" srcset="static/litmus-logo-dark.svg" /> <img src="static/litmus-logo-light.svg" height="60" alt="Litmus logo" /> </picture> </a> </p> <p align="center"> <a href="https://docs.litmus.io"> <img src="https://img.shields.io/badge/Litmus-Docs-2acfa6?style=flat-square" alt="Documentation" /> </a> <a href="https://www.linkedin.com/company/litmus-automation/" > <img src="https://img.shields.io/badge/LinkedIn-Follow-0a66c2?style=flat-square" alt="Follow on LinkedIn" /> </a> </p> # Litmus MCP Server The official [Litmus Automation](https://litmus.io) **Model Context Protocol (MCP) Server** enables LLMs and intelligent systems to interact with [Litmus Edge](https://litmus.io/products/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](https://modelcontextprotocol.io/). <div> <picture> <source media="(prefers-color-scheme: light)" srcset="static/MCP-server-arch-diagram.png" /> <img src="static/MCP-server-arch-diagram.png" alt="Litmus MCP Server Architecture Diagram" /> </picture> </div> ## Table of Contents - [Getting Started](#getting-started) - [Quick Launch (Docker)](#quick-launch-docker) - [Cursor IDE Setup](#cursor-ide-setup) - [Tools](#available-tools) - [Usage](#usage) - [Server-Sent Events (SSE)](#server-sent-events-sse) - [Litmus Central](#litmus-central) - [Integrations](#integrations) - [Cursor IDE](#cursor-ide) - [Claude Desktop](#claude-desktop) - [VS Code / Copilot](#vs-code--copilot) - [Windsurf](#windsurf) --- ## Getting Started ### Quick Launch (Docker) Run the server in Docker: ```bash docker run -d --name litmus-mcp-server -p 8000:8000 ghcr.io/litmusautomation/litmus-mcp-server:latest ``` ### Cursor IDE Setup Example `mcp.json` configuration: ```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>" } } } } ``` **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 See the [Cursor docs](https://docs.cursor.com/context/model-context-protocol) for more info. --- ## Available Tools | Category | Function Name | Description | |---------------------------|----------------------------------------|-------------| | **DeviceHub** | `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_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. | | **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** ** | `get_historical_data_from_influxdb` | Query historical time-series data from InfluxDB by measurement and time range. | | **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. | ### Configuration 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 Tools Requirements:** To use `get_historical_data_from_influxdb`, 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 --- ## Usage ### Server-Sent Events (SSE) This server supports the [MCP SSE transport](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse) for real-time communication. - **Client endpoint:** `http://<server-ip>:8000/sse` - **Default binding:** `0.0.0.0:8000/sse` - **Communication:** - Server → Client: Streamed via SSE - Client → Server: HTTP POST --- ## Litmus Central Download or try Litmus Edge via [Litmus Central](https://central.litmus.io). --- ## Integrations ### Cursor IDE Add to `~/.cursor/mcp.json` or `.cursor/mcp.json`: ```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](https://docs.cursor.com/context/model-context-protocol) --- ### Claude Desktop Add to `claude_desktop_config.json`: ```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>" } } } } ``` [Anthropic Docs](https://docs.anthropic.com/en/docs/agents-and-tools/mcp) --- ### VS Code / GitHub Copilot #### Manual Configuration In VS Code: Open User Settings (JSON) → Add: ```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>" } } } } ``` Or use `.vscode/mcp.json` in your project. [VS Code MCP Docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) --- ### Windsurf Add to `~/.codeium/windsurf/mcp_config.json`: ```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](https://docs.windsurf.com/windsurf/mcp) ### MCP server registries - [Glama](https://glama.ai/mcp/servers/@litmusautomation/litmus-mcp-server) <a href="https://glama.ai/mcp/servers/@litmusautomation/litmus-mcp-server"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@litmusautomation/litmus-mcp-server/badge" alt="Litmus MCP server" /> </a> - [MCP.so](https://mcp.so/server/litmus-mcp-server/litmusautomation) --- © 2025 Litmus Automation, Inc. All rights reserved.