Skip to main content
Glama
uc-remote-mcp

uc-remote-mcp

by b2dmx
README.md
<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark.png">
    <img src="docs/logo.png" height="150" alt="Unfolded Circle MCP">
  </picture>
</p>

<p align="center"><b>Set up and control your Unfolded Circle remote by just asking.</b></p>

<p align="center">
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Server-6103FF" alt="MCP Server"></a>
  <a href="https://ko-fi.com/goobis2dmx"><img src="https://img.shields.io/badge/Ko--fi-Support-FF5E5B?logo=kofi&logoColor=white" alt="Support on Ko-fi"></a>
</p>

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](https://docs.astral.sh/uv/getting-started/installation/).** You already have it if you use another Python MCP server.

   ```powershell
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows
   ```
   ```sh
   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):

   ```json
   {
     "mcpServers": {
       "uc-remote": {
         "command": "uvx",
         "args": ["--from", "git+https://github.com/b2dmx/uc-remote-mcp@v1.0.0", "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 →](docs/tools.md) · [Field notes →](docs/notes.md)

Tool design informed by [ha-mcp](https://pypi.org/project/ha-mcp/). API reference from the [Unfolded Circle Core API](https://github.com/unfoldedcircle/core-api).

## License

The code is [MIT](LICENSE). 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.

---

<p align="center">
  <a href="LICENSE">MIT</a> · <a href="https://ko-fi.com/goobis2dmx">Support on Ko-fi</a> · Unofficial community project, not affiliated with or endorsed by Unfolded Circle<br><br>
  Unfolded Circle MCP v1.0.0 by Goobis<br>
  AI was used to help develop this application
</p>

TDQS

B3.2/5.0

Scored across 41 tools

Disambiguation4/5

Most tools target a distinct resource+action, and descriptions explicitly disambiguate close pairs like delete_integration vs delete_integration_instance and answer vs confirm_integration_setup. A few entity-listing tools (list_devices, list_integration_entities, list_scope_entities) require careful reading, but their scope qualifiers make selection possible.

Naming Consistency5/5

All tools use snake_case verb_noun names with consistent verbs (list/get/create/update/delete/set/restart). Pluralization is predictable (list_* plural, get_* singular), and modifiers like bulk_ and diff_ are used consistently.

Tool Count2/5

At 41 tools, the surface is far beyond the typical 3-15 tool sweet spot and falls in the 'too many' range even for a broad remote-control domain. While most tools are individually justified, the count makes selection harder and suggests consolidation opportunities.

Completeness3/5

The surface covers integration lifecycle, setup flows, devices, activities, UI pages, mappings, and backup/restore, which is broad. However, activities have create/get/partial update but no delete/rename, and backup_config has no companion list_backups tool, leaving some dead ends.

Maintenance

ActivityNo data
ResponsivenessOutdated data