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 companion there), this package is the
right tool. aiui registers it automatically when you add the remote in
settings — {command: "uvx", args: ["aiui-mcp==<version>"]}, pinned to the
version of your companion so the two always speak the same contract (uvx
may be an absolute path when aiui found one on the remote). 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 |
Client timeout for the companion requests that are not polls: opening a dialog (POST /render), pushing local video/audio to the media cache (/media), /notify and /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_ALLOW_UNVERIFIED_COMPANION |
unset | Set to 1 to send the token to a companion too old to answer the challenge probe. Before its token leaves this host, the bridge makes the listener on the companion port prove it holds the same token (GET /probe?nonce=…, HMAC answer); a listener that cannot is refused, because on a shared host anything may hold that port while the SSH tunnel is down. Only an older companion answering 401 can be let through, and only with this opt-in — better: update aiui. |
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.12.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 | Provenance | |
|---|---|---|---|---|
| aiui_mcp-0.12.0.tar.gz | 64.0 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| aiui_mcp-0.12.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 129.0 kB
Release files / aiui_mcp-0.12.0.tar.gz
| Download URL | aiui_mcp-0.12.0.tar.gz |
|---|---|
| Size | 64.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
015b1433097bd1d969311fe72e77c97f40072f50c76ef13d10703effde493df3
|
|
BLAKE2b-256 checksum How to use checksums |
e6d4ced4b196531e6279a16021d8419ee71ec8c92dc92651d1554d100d44fd31
|
| 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.12.0-py3-none-any.whl
| Download URL | aiui_mcp-0.12.0-py3-none-any.whl |
|---|---|
| Size | 65.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
646aecfa58974dcff35b011786707ff9ec47f7b108a70a137081bfbabb575930
|
|
BLAKE2b-256 checksum How to use checksums |
7a096a00dc91e7d3b37628f95e09791374cddecdd81c9cb2bb6d74565e558b05
|
| 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}
|
Security for aiui-mcp 0.12.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
