uc-remote-mcp

Set up and control your Unfolded Circle remote by just asking.

An MCP server for the Remote 3 / Remote Two. Works with Claude and any other MCP client.

What it does

• Layouts: build an activity, device or page.
• Buttons: ask what a button does, or remap it.
• Integrations: install, set up and restart them.
• Backups: snapshot your config, see what changed, restore it.
• Updates: keep the remote current.

Installation

1. Install uv. You already have it if you use another Python MCP server.

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows
   

   curl -LsSf https://astral.sh/uv/install.sh | sh                                    # macOS / Linux
   

2. Add it to your MCP client. For Claude Desktop, edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

   {
     "mcpServers": {
       "uc-remote": {
         "command": "uvx",
         "args": ["--from", "git+https://github.com/b2dmx/[email protected]", "uc-remote-mcp"]
       }
     }
   }
   

3. Restart the client. First launch takes a minute while it builds.

Onboarding

1. On the remote: Settings → Web Configurator, turn it on and note the PIN.
2. Tell your AI: "Discover my Unfolded Circle remote and set it up with PIN 1234."
3. Try: "What does the volume button do in each activity?"

Tips

• Every change previews first and takes a backup, so it's safe to experiment.
• Say "Back up my config" before big changes, and "What changed since that backup?" after.
• Removing an entity also strips the buttons and page items using it.
• A stopped device? "Restart the Apple TV integration."
• To update, change the version in your config and restart. Watch → Custom → Releases to hear about new ones.
• Tested on a Remote 3 (firmware 2.8.x). The Remote Two shares the API but is untested.

More

All the tools → · Field notes →

Tool design informed by ha-mcp. API reference from the Unfolded Circle Core API.

License

The code is MIT. The Unfolded Circle MCP logo and icons (brand-source/, brand/, and the logo images in docs/) are © Goobis, all rights reserved. They are not covered by the MIT license, so please don't reuse them without permission.

MIT · Support on Ko-fi · Unofficial community project, not affiliated with or endorsed by Unfolded Circle

Unfolded Circle MCP v1.0.0 by Goobis
AI was used to help develop this application