aiui-mcp
MCP server for aiui — lets Claude Code sessions render native desktop dialogs on the user's own machine (macOS, and Windows since aiui 0.10.1). Works for local and remote Claude Desktop App setups.
Install
You don't normally need to touch this package directly.
On your own machine, install aiui
— since v0.3.0 the MCP server is bundled as native Rust code inside the
app. ~/.claude.json points directly at the app binary. No uv, no
uvx, no Python on the onboarding path.
On a remote SSH host (no aiui.app there), this package is the right
tool. aiui registers it automatically when you add the remote in
settings — {command: "uvx", args: ["aiui-mcp"]}. All dialogs tunnel
back through aiui on your own machine.
See the main repo for the full install flow and companion download: https://github.com/byte5ai/aiui
Tools
confirm— hard yes/no with optional destructive stylingask— single- or multi-choice with per-option descriptionsform— composite window with typed fields and action buttonsgallery— image/video grid the user picks fromcompare— side-by-side diff of two texts or imagesupload— native file picker on the user's machine; the chosen file lands on the agent hostnotify— fire-and-forget OS notification, no dialog, no replyaiui_health— reachability checkversion— companion version, build info, binary path, updater endpointupdate— silent update check + install on the user's machine
Environment variables
None of these need setting — the defaults are what aiui registers for you. A bad value is warned about and ignored, never fatal: a typo in one of these must not turn into "the aiui MCP server failed to start".
| Variable | Default | Meaning |
|---|---|---|
AIUI_ENDPOINT |
http://127.0.0.1:7777 |
Companion base URL — the local end of the SSH reverse-tunnel. |
AIUI_TOKEN_PATH |
~/.config/aiui/token (%APPDATA%\aiui\token on Windows) |
Pairing token file, written by the companion and copied to each registered remote. |
AIUI_TIMEOUT_S |
120 |
Seconds for a held request (/notify, /update). |
AIUI_HEALTH_TIMEOUT_S |
3 |
Seconds for aiui_health and /version — deliberately short; it is the diagnostic. |
AIUI_COLDSTART_WAIT_S |
30 |
Seconds to poll /ping before the first call, so a companion that is still starting gets time to serve. |
AIUI_UPLOAD_TIMEOUT_S |
900 |
Seconds for the held POST /upload — generous, because the user browses a file picker inside it. |
AIUI_LOG_LEVEL |
INFO |
Any standard logging level name. |
AIUI_LIVE |
unset | Test-only: set to 1 to run the integration tests against a real companion. |
Prompts
/aiui:teach— briefs the agent on aiui (full widget catalog, design rules, anti-patterns)/aiui:update— agent calls theupdatetool and reports the outcome/aiui:version— reports the installed aiui version in one line/aiui:health— one-line health check of the companion/aiui:test-dialog— pops a demo dialog to verify the wiring end to end/aiui:remotes— lists the registered aiui remotes in chat/aiui:upload— hands a file from the user's machine to the agent session
License
MIT — see LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for aiui-mcp 0.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| aiui_mcp-0.11.0.tar.gz | 53.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| aiui_mcp-0.11.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 108.6 kB
Release files / aiui_mcp-0.11.0.tar.gz
| Download URL | aiui_mcp-0.11.0.tar.gz |
|---|---|
| Size | 53.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c58f3b06fe89460e1c166eb0f781281a0297121fe35c4ddb4ee881c020e3803c
|
|
BLAKE2b-256 checksum How to use checksums |
89b5e92a32c2d7f7e197f9c8839d60101659cfd6e3361ac01b81194092e01d9d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / aiui_mcp-0.11.0-py3-none-any.whl
| Download URL | aiui_mcp-0.11.0-py3-none-any.whl |
|---|---|
| Size | 54.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3c5703097c5c8d3db29eddd2effc802333478bfdba74fb6eb5a80f7ab7ec6f06
|
|
BLAKE2b-256 checksum How to use checksums |
966c9cb7960db648bd9ebe2708170b85c1e2eb68429e7fb95068c6337664b1e6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
