Indigo MCP Lite

A stdlib-only Model Context Protocol server for Indigo, packaged as an Indigo plugin. Lets AI assistants like Claude search, control, and reason about your Indigo devices through natural language.

Why "lite"? This plugin replaces mlamoure/indigo-mcp-server for users who can't run that plugin's vector-search dependencies (LanceDB requires AVX2 + Apple Silicon or recent Intel; on Indigo 2025.2 / Python 3.13 the LanceDB wheels stopped installing on Intel Macs entirely). Lite uses SQLite FTS5 instead — built into Python's stdlib, no native deps, no external API keys, no embeddings. Search is keyword-and-alias rather than semantic, but it's fast (<50ms over ~2k entities) and runs anywhere Indigo runs.

What it does

Ask Claude things like:

• "How many dimmers do I have in the kitchen?"
• "Find all leak sensors"
• "Turn the bedroom lamp to 30% warm white"
• "What's the heating setpoint for the living room?"
• "Show me errors in the event log from the last hour"
• "Run the goodnight scene"

Lite exposes 72 MCP tools — full read access to devices/variables/action groups/triggers/schedules, automation contents (decoded action steps, condition trees, and embedded scripts read from the Indigo database file), write control of dimmers/relays/thermostats/variables/action groups, system introspection (event log, plugin status), and a single FTS5-backed find_devices search. Device details are enriched with capability flags from a vendored snapshot of the community device catalog (regenerated per release — no network at runtime), the colour/white control tools use the same data for friendly refusals on unsupported devices, and list_uncataloged_devices reports the catalog gaps.

Server requirements

• Indigo Domotics: 2024.2 or later
• macOS: any version Indigo supports — lite has no native dependencies
• CPU: Intel or Apple Silicon — no AVX2 requirement, no embeddings library
• Python: 3.10+ (Indigo bundles its own; nothing extra to install)
• Pip dependencies: zero (SQL Logger history works via stdlib sqlite3, or the psql CLI for PostgreSQL — no psycopg2)

This is the whole point of "lite" — install on any Indigo-supported Mac and it works.

Installation

1. Download the latest Indigo MCP Lite.indigoPlugin.zip from the Releases page.
2. First-time install: double-click the unzipped .indigoPlugin to install via Indigo. Subsequent updates can be cp-deployed, but the very first install must go through the Indigo UI so it registers properly.
3. Enable the plugin in Indigo: Plugins → Indigo MCP Lite → Enable.
4. No configuration needed — lite runs the moment it's enabled. The MCP endpoint is exposed automatically at https://<your-indigo-host>/message/com.simons-plugins.indigo-mcp-lite/mcp via Indigo's IWS.

Authentication

Authentication is enforced by Indigo's Web Server (IWS), in front of the plugin — the plugin itself performs no Authorization check and never sees your credentials. Requests without a valid Bearer token are rejected by IWS before the MCP endpoint is invoked. Use either:

• Local secret for LAN access — set up via secrets.json per Indigo's local secrets docs and pass as Authorization: Bearer <local-secret>.
• Reflector API key for remote access — issued from your Indigo Reflector settings.

Consequently, do not expose IWS's port directly to the internet without the local secret configured: with IWS auth disabled or bypassed there is no second line of defence, and every tool — including the control tools — would be reachable unauthenticated.

Claude Code / Claude Desktop configuration

Two configuration patterns. Pick the one that matches your situation.

Pattern A — Drop-in replacement (recommended for most users)

Replace mlamoure's indigo MCP server entry with lite. Keeps the mcp__indigo__* tool namespace and existing muscle memory; best when lite is your only Indigo MCP.

In your Claude Code project's .mcp.json (with the dot — Claude Code reads this; not mcp.json):

{
  "mcpServers": {
    "indigo": {
      "command": "/opt/homebrew/bin/npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-reflector.indigodomo.net/message/com.simons-plugins.indigo-mcp-lite/mcp",
        "--header",
        "Authorization:Bearer YOUR_TOKEN"
      ],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

For Claude Desktop, the equivalent file is ~/Library/Application Support/Claude/claude_desktop_config.json.

Check your npx path first. The examples use Homebrew's /opt/homebrew/bin/npx, but Node installed via the nodejs.org installer lives in /usr/local/bin — even on Apple Silicon. Run which npx in a terminal and use that path for command, and make sure the directory it printed is the first entry in env.PATH (npx's #!/usr/bin/env node shebang re-resolves node via that PATH, so command alone isn't enough). A wrong command path fails silently — the server just shows as disconnected with no request ever leaving your machine.

Pattern B — Side-by-side with mlamoure

Use a distinct key so the tool prefixes don't collide. Tools appear under mcp__indigo_mcp_lite__*.

{
  "mcpServers": {
    "indigo": {
      "command": "/opt/homebrew/bin/npx",
      "args": [
        "-y", "mcp-remote",
        "https://your-reflector.indigodomo.net/message/com.vtmikel.mcp_server/mcp/",
        "--header", "Authorization:Bearer YOUR_TOKEN"
      ],
      "env": {"PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"}
    },
    "indigo-mcp-lite": {
      "command": "/opt/homebrew/bin/npx",
      "args": [
        "-y", "mcp-remote",
        "https://your-reflector.indigodomo.net/message/com.simons-plugins.indigo-mcp-lite/mcp",
        "--header", "Authorization:Bearer YOUR_TOKEN"
      ],
      "env": {"PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"}
    }
  }
}

Pick this if you want to keep mlamoure's semantic search on Apple Silicon and lite's lightweight stdlib path for the simpler queries.

LAN-only configuration

For local access without the Reflector, swap the URL host:

https://jarvis.local:8176/message/com.simons-plugins.indigo-mcp-lite/mcp

(Replace jarvis.local with your Indigo server's hostname; 8176 is IWS's HTTPS port.) Use your local secret as the Bearer token.

Important configuration gotchas

These bit us during setup; surfaced here so they don't bite you.

.mcp.json (with the dot) vs mcp.json (no dot)

Claude Code reads .mcp.json (dotfile) for project-local MCP servers. Cowork and some other tools read mcp.json (no dot). The two files are independent — editing the wrong one silently does nothing for the other tool. If lite's namespace doesn't appear in Claude Code's available tools after restart, first check you edited .mcp.json (the dotfile).

Pin Node via env.PATH

mcp-remote's undici dependency requires Node ≥ 18. If your shell has an older Node first on PATH (common with nvm), the bridge crashes at import with ReferenceError: ReadableStream is not defined and Claude Code shows "Server disconnected" with no further detail.

The env.PATH block in the configs above pins Homebrew's Node to the front of PATH for the bridge subprocess only, sidestepping the issue without changing your shell setup.

Don't use type: "http" in Claude Code's MCP config

Claude Code's type: "http" form expects Server-Sent Events (SSE) transport. Lite (and Home Intelligence) speak plain HTTP POST JSON-RPC, not SSE — the connection silently fails at session start. Use the mcp-remote bridge form (command + args + env) instead. mcp-remote translates between Claude Code's SSE expectation and the plugin's plain JSON-RPC.

Cold-start race

If mcp-remote isn't yet cached locally, npx -y mcp-remote ... has to fetch the package on first run, which can exceed Claude Code's MCP-server-startup timeout. After mcp-remote runs once and is cached, subsequent session starts are fast. If the namespace is missing on the first session, run npx -y mcp-remote --help once manually to warm the cache, then start a fresh Claude Code session.

Restarting lite itself

restart_plugin deliberately refuses to restart com.simons-plugins.indigo-mcp-lite — a self-restart kills the in-flight MCP request mid-response. To restart lite, use Indigo's Plugins menu (Plugins → Indigo MCP Lite → Reload) or another MCP client pointed at a different Indigo plugin.

Tools

Lookup tools (19)

Automation contents tools (3)

Control tools (42)

History tools (2)

System tools (5)

Search tools (1)

To regenerate the table from the live registry: python3 scripts/generate_tool_doc.py. Single source of truth is tool_registry.register_all — adding a tool to any tools/*.py module automatically shows up on the next regenerate.

Search behaviour

find_devices indexes every device, variable, and action group at plugin start, then keeps the index live via Indigo's change-subscription callbacks. Static-field changes (renames, folder moves, description edits) trigger a per-row reindex; volatile state changes (brightness, sensor readings, variable value flips) do not — verified at ~1 reindex per minute on a 1,891-entity install.

The FTS5 schema indexes name, description, type label, folder, and a curated list of type aliases (so "light" finds anything whose deviceTypeId is in the dimmer family even if the device itself isn't named "light"). bm25 weights favour name matches (3.0) over alias matches (2.0) over folder/description (1.0–1.5). The full alias list is in type_aliases.py — adding entries is a one-line change.

Verifying it works

After configuring Claude, ask:

"Using indigo-mcp-lite, find all dimmers in the kitchen."

Claude should call find_devices with query="kitchen", type="dimmer" (or similar) and return the matching devices. If you see a Server disconnected error or the namespace doesn't appear, walk through the configuration gotchas above.

Architecture

• MCP transport: hand-rolled JSON-RPC 2.0 dispatcher copied verbatim from sister plugin Home Intelligence — speaks MCP protocol versions 2025-11-25 and 2025-06-18.
• Tool surface: each tool group lives in tools/<group>.py and registers itself via tool_registry.register_all. Adding a new tool family is a one-file addition.
• Index: indexer.py maintains an in-memory SQLite FTS5 table over indigo.devices / indigo.variables / indigo.actionGroups, refreshed via change-subscription callbacks on plugin.py.
• Zero pip dependencies in production. pytest is the only test-time dependency.

For the design rationale (FTS5 vs vector search, in-memory vs on-disk, alias-based lexical bridging instead of embeddings), see docs/adr/0001-fts5-not-vector-search.md (lands in Phase 8).

Development

git clone https://github.com/simons-plugins/indigo-mcp-lite
cd indigo-mcp-lite

# Run the test suite (~1s)
/Library/Frameworks/Python.framework/Versions/3.11/bin/pytest tests/ -q

# Regenerate the README's tool table
python3 scripts/generate_tool_doc.py

Contributions welcome — small synonym additions to type_aliases.py are especially valuable.

License

MIT — see LICENSE.