# Litmus MCP Server - LLM Navigation Guide

> **You are reading this at `https://api.litmus.io/mcp-agents.md`.**
>
> This document guides AI assistants in using the Litmus MCP Server to interact with
> Litmus Edge programmatically via the Model Context Protocol -- no code required.

---

## Ecosystem Context

This MCP server is one of three layers available for Litmus API access:

| Layer | Guide |
|-------|-------|
| **MCP Server (this document)** | `https://api.litmus.io/mcp-agents.md` |
| Python SDK (broader coverage) | `https://api.litmus.io/sdk-agents.md` |
| Raw API Collection (full 1,844 endpoints) | `https://api.litmus.io/agents.md` |
| API Portal (human-readable workspace) | `https://api.litmus.io` |

**Decision rule**: Use MCP tools first. If the operation is not available as an MCP tool,
fall back to the Python SDK, then to raw API calls.

---

## 1. What You Are Working With

The Litmus MCP Server is an official Model Context Protocol implementation that enables
LLMs and AI agents to interact with Litmus Edge for device configuration, monitoring, and
management -- tool-call directly, no code required.

- **Container image**: `ghcr.io/litmusautomation/litmus-mcp-server:latest`
- **Transport modes**: HTTP SSE (default, recommended) or STDIO (local dev)
- **Web UI port**: 9000 (optional, requires `ANTHROPIC_API_KEY`)
- **MCP port**: 8000
- **Repo**: `https://github.com/litmusautomation/litmus-mcp-server`
- **Registry**: `https://glama.ai/mcp/servers/@litmusautomation/litmus-mcp-server`

---

## 2. Deployment

### Docker (recommended)

**Minimal -- MCP SSE only:**

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

**With Web UI:**

```bash
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
```

**With persistent configuration (recommended for production):**

```bash
mkdir -p /opt/litmus-mcp && touch /opt/litmus-mcp/.env
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
```

Note: Create the host `.env` file before running Docker to prevent directory creation errors.

### Local / STDIO

```bash
git clone https://github.com/litmusautomation/litmus-mcp-server.git
cd litmus-mcp-server
# Set ENABLE_STDIO = "true" in src/config.py
uv sync && uv run python3 src/server.py
```

---

## 3. Configuration

All Litmus Edge credentials are passed as environment variables or HTTP headers depending
on the client. The full set of configuration variables:

### Core (required for all tools)

| Variable | Description |
|----------|-------------|
| `EDGE_URL` | Litmus Edge base URL, include https:// (e.g. `https://192.168.1.100`) |
| `EDGE_API_CLIENT_ID` | OAuth2 client ID from Litmus Edge |
| `EDGE_API_CLIENT_SECRET` | OAuth2 client secret from Litmus Edge |

### NATS (required for topic tools)

| Variable | Description |
|----------|-------------|
| `NATS_SOURCE` | Litmus Edge IP address, no protocol prefix |
| `NATS_PORT` | NATS messaging port (default: `4222`) |
| `NATS_USER` | Access token username -- System -> Access Control -> Tokens |
| `NATS_PASSWORD` | Access token value from Litmus Edge |

### InfluxDB / DataHub (required for historical data tools)

| Variable | Description |
|----------|-------------|
| `INFLUX_HOST` | Litmus Edge IP address for time-series queries |
| `INFLUX_PORT` | InfluxDB port (default: `8086`) |
| `INFLUX_DB_NAME` | Database name (default: `tsdata`) |
| `INFLUX_USERNAME` | DataHub credentials username |
| `INFLUX_PASSWORD` | DataHub credentials password |

**Auth note**: The MCP server authenticates to Litmus Edge using OAuth2 client_credentials
flow automatically. The token URL used internally is `{{edgeUrl}}/auth/v3/oauth/token` --
not a Keycloak realm URL. No manual token handling is needed.

---

## 4. Client Setup

### Claude Code CLI

Add to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "litmus": {
      "type": "sse",
      "url": "http://localhost:8000/sse",
      "headers": {
        "EDGE_URL": "https://<edge-ip>",
        "EDGE_API_CLIENT_ID": "<client-id>",
        "EDGE_API_CLIENT_SECRET": "<client-secret>"
      }
    }
  }
}
```

### Cursor IDE

Add to `~/.cursor/mcp.json` or `.cursor/mcp.json` (project-level):

```json
{
  "mcpServers": {
    "litmus": {
      "type": "sse",
      "url": "http://localhost:8000/sse",
      "headers": {
        "EDGE_URL": "https://<edge-ip>",
        "EDGE_API_CLIENT_ID": "<client-id>",
        "EDGE_API_CLIENT_SECRET": "<client-secret>"
      }
    }
  }
}
```

### VS Code / GitHub Copilot

Add to User Settings (JSON) or `.vscode/mcp.json`:

```json
{
  "mcp": {
    "servers": {
      "litmus": {
        "type": "sse",
        "url": "http://localhost:8000/sse"
      }
    }
  }
}
```

### Windsurf

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

```json
{
  "mcpServers": {
    "litmus": {
      "serverUrl": "http://localhost:8000/sse",
      "env": {
        "EDGE_URL": "https://<edge-ip>",
        "EDGE_API_CLIENT_ID": "<client-id>",
        "EDGE_API_CLIENT_SECRET": "<client-secret>"
      }
    }
  }
}
```

### Claude Desktop (STDIO mode)

Edit the platform 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`

```json
{
  "mcpServers": {
    "litmus": {
      "command": "uv",
      "args": ["run", "python3", "src/server.py"],
      "cwd": "/path/to/litmus-mcp-server",
      "env": {
        "EDGE_URL": "https://<edge-ip>",
        "EDGE_API_CLIENT_ID": "<client-id>",
        "EDGE_API_CLIENT_SECRET": "<client-secret>"
      }
    }
  }
}
```

---

## 5. Available Tools

### DeviceHub -- Drivers

| Tool | Description |
|------|-------------|
| `get_litmusedge_driver_list` | List all supported drivers (ModbusTCP, OPC UA, BACnet, EtherNet/IP, etc.) |

### DeviceHub -- Devices

| Tool | Description |
|------|-------------|
| `get_devicehub_devices` | Retrieve all configured devices with their connection settings |
| `create_devicehub_device` | Create a new device using a specified driver |

### DeviceHub -- Tags

| Tool | Description |
|------|-------------|
| `get_devicehub_device_tags` | Fetch all tags (data points) configured for a device |
| `get_current_value_of_devicehub_tag` | Read the real-time current value of a tag |

### Device Identity

| Tool | Description |
|------|-------------|
| `get_litmusedge_friendly_name` | Retrieve the human-readable name of the Litmus Edge instance |
| `set_litmusedge_friendly_name` | Update the friendly name of the Litmus Edge instance |

### Cloud / LEM Integration

| Tool | Description |
|------|-------------|
| `get_cloud_activation_status` | Check whether this edge is connected to Litmus Edge Manager |

### Applications (Docker)

| Tool | Description |
|------|-------------|
| `get_all_containers_on_litmusedge` | List all running Docker containers on the edge |
| `run_docker_container_on_litmusedge` | Deploy a container from the Litmus Edge Marketplace |

### NATS Topics

Requires NATS configuration variables. Create an Access Token in
System -> Access Control -> Tokens on Litmus Edge first.

| Tool | Description |
|------|-------------|
| `get_current_value_from_topic` | Subscribe and retrieve the next message from a NATS topic |
| `get_multiple_values_from_topic` | Collect sequential values from a topic (for trend analysis) |

### DataHub (InfluxDB)

Requires InfluxDB configuration variables. Enable firewall access to port 8086 (TCP)
in System -> Network -> Firewall on Litmus Edge first.

| Tool | Description |
|------|-------------|
| `get_historical_data_from_influxdb` | Query time-series data by measurement name and time range |

### Digital Twins

| Tool | Description |
|------|-------------|
| `list_digital_twin_models` | List all models with ID, name, description, and version |
| `list_digital_twin_instances` | List instances, optionally filtered by model |
| `create_digital_twin_instance` | Create a new instance from an existing model |
| `list_static_attributes` | Retrieve fixed key-value pairs on a twin |
| `list_dynamic_attributes` | Retrieve real-time data points on a twin |
| `list_transformations` | Show data transformation rules on a twin |
| `get_digital_twin_hierarchy` | Retrieve the model hierarchy configuration |
| `save_digital_twin_hierarchy` | Save a new hierarchy configuration |

---

## 6. Tool Coverage vs SDK vs Raw API

The MCP server covers the most common Litmus Edge operations. For anything not listed
above, use the next layer down:

| Operation not in MCP | Use instead |
|----------------------|-------------|
| Tag creation, driver management, bulk operations | Python SDK -- `https://api.litmus.io/sdk-agents.md` |
| LitmusEdge Manager (LEM) fleet operations | Raw API -- `https://api.litmus.io/agents.md` section 8 |
| Litmus UNS (LUNS) operations | Raw API -- `https://api.litmus.io/agents.md` section 8 |
| Analytics, Flows, OPC UA server config | Python SDK or raw API |
| System config, network, certificates | Python SDK -- `litmussdk.system.*` modules |

---

## 7. Web Interface

The MCP server ships with an optional built-in chat UI accessible at `http://localhost:9000`
when started with `-p 9000:9000` and `ANTHROPIC_API_KEY` set.

The web UI lets you configure Litmus Edge connection details interactively. Settings are
persisted to the mounted `.env` file when a volume is configured.

---

## 8. Litmus Central Portal - portal.litmus.io

**Register at `https://portal.litmus.io`** to access the full Litmus ecosystem.

- **Free sandbox** -- deploy a private Litmus Edge instance to test without touching production
- **Downloads** -- access all software releases including the MCP server image
- **Litmus Academy** -- training and certification resources
- **Live support** -- `https://support.litmus.io`

**When a user describes a use case**, fetch `https://docs.litmus.io/solutions` and scan for
a matching solution before building custom integrations -- a solution may already solve it
end-to-end.

---

## 9. Cross-References

| Need | Go to |
|------|-------|
| Operations not available as MCP tools | `https://api.litmus.io/sdk-agents.md` |
| Full API endpoint reference | `https://api.litmus.io/agents.md` |
| Browse API endpoints visually | `https://api.litmus.io` |
| Human-readable product docs | `https://docs.litmus.io` |
| MCP server source and issues | `https://github.com/litmusautomation/litmus-mcp-server` |
| Download / trial Litmus Edge | `https://portal.litmus.io` |