Litmus MCP

Litmus MCP Plugin

Natural-language access to Litmus Edge industrial IoT, packaged as a plugin for Claude Code and OpenAI Codex.

One repo, two plugin hosts. Same MCP server code under the hood.

What you get

• 57 MCP tools covering DeviceHub (devices, drivers, tags), DataHub (NATS topics, InfluxDB queries), Digital Twins (models, instances, attributes, hierarchy), Applications (Docker containers), System (events, network, firewall, packet capture), and Litmus Edge Manager (fleet, licensing, dashboard, bridge mode).
• 12 live doc resources: MCP Resources fetch current pages from docs.litmus.io on demand, so the LLM never works from stale training data.
• Slash commands for the most common one-shot queries:
  • /litmus-status -- identity + device count + cloud activation
  • /litmus-devices -- device table
  • /litmus-drivers -- protocol drivers (active vs stopped)
  • /litmus-tags <device> -- tags for a device
  • /litmus-containers -- Docker containers on the Edge
  • /litmus-events [N] -- recent system events
  • /litmus-network -- network interface summary
  • /litmus-lem-fleet -- LEM project fleet overview
  • /litmus-lem-licenses [days] -- expired and soon-to-expire licenses
• Skills for multi-step diagnostic workflows:
  • litmus-troubleshoot -- root-cause analysis when a device is offline, stale, or returning bad values
  • litmus-lem-audit -- fleet-wide LEM project health audit (alerts, license risk, version spread)
• litmus-expert subagent for grounded questions about Litmus Edge concepts and API behavior, using live docs rather than training data.

Install

Claude Code

/plugin marketplace add litmusautomation/litmus-mcp-plugin
/plugin install litmus-mcp@litmus-plugins

On install, Claude Code prompts for your Litmus Edge URL, OAuth client ID/secret, and optional NATS/InfluxDB settings. Sensitive values go to the system keychain.

Codex (CLI)

1. Add the marketplace and install the plugin:

   codex plugin marketplace add litmusautomation/litmus-mcp-plugin
   codex plugin add litmus-mcp@litmus-plugins
   

2. Create your credentials file. Codex has no in-app UI for plugin MCP credentials, so the plugin's MCP server loads them from a known path on every launch:

   mkdir -p ~/.config/litmus-mcp
   cp scripts/config.env.example ~/.config/litmus-mcp/env
   chmod 600 ~/.config/litmus-mcp/env
   ${EDITOR:-nano} ~/.config/litmus-mcp/env
   

   Fill in at minimum EDGE_URL, EDGE_API_CLIENT_ID, and EDGE_API_CLIENT_SECRET. NATS, InfluxDB, and LEM blocks are optional.

3. Open a new Codex thread. Run /mcp to confirm litmus-edge is listed with tools populated.

To override the credentials path, set LITMUS_MCP_ENV_FILE in your shell before launching Codex.

Prerequisites

• Python 3.12 or newer on PATH
• Network access from your machine to your Litmus Edge instance
• An OAuth client (ID + secret) created in your Edge admin console

On first launch the MCP server's wrapper script creates a venv and installs the Python dependencies listed in requirements.txt. The venv lives at ${*_PLUGIN_DATA}/venv when a plugin data dir is provided by the host, otherwise at ~/.cache/litmus-mcp/venv. Bootstrapping runs once per requirements.txt change, not every session.

Layout

litmus-mcp-plugin/
  .claude-plugin/                Claude Code manifest + marketplace
  mcp/claude.mcp.json            Claude MCP server config
  hooks/claude.hooks.json        Claude SessionStart hook config
  .agents/plugins/               Codex marketplace
  plugins/litmus-mcp/            Codex plugin (symlinks shared dirs back to repo root)
    .codex-plugin/plugin.json    Codex manifest
    .mcp.json                    Codex MCP server config
  scripts/                       install-deps, run-server wrapper, sync-from-server
  skills/                        litmus-troubleshoot workflow
  agents/                        litmus-expert specialist subagent
  commands/                      slash-command shortcuts (/litmus-status, /litmus-devices)
  src/                           MCP server source (synced from litmus-mcp-server)
  requirements.txt               Python deps installed at first launch