{ "markdown": "# open-mcp-apps\n\n[![CI](https://github.com/2nd1st/open-mcp-apps/actions/workflows/ci.yml/badge.svg)](https://github.com/2nd1st/open-mcp-apps/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/%402nd1st%2Fopen-mcp-apps?logo=npm&label=npm)](https://www.npmjs.com/package/@2nd1st/open-mcp-apps)\n[![license](https://img.shields.io/npm/l/%402nd1st%2Fopen-mcp-apps)](LICENSE)\n[![node](https://img.shields.io/node/v/%402nd1st%2Fopen-mcp-apps)](package.json)\n[![MCP Registry](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0%2Fservers%3Fsearch%3Dopen-mcp-apps%26version%3Dlatest&query=%24.servers%5B0%5D.server.version&label=MCP%20Registry&color=blue&prefix=v)](https://registry.modelcontextprotocol.io/v0/servers?search=open-mcp-apps&version=latest)\n\n**English** | [简体中文](i18n/README.zh-CN.md)\n\n> Give your AI a persistent, reusable UI. It builds the app once — you keep it forever.\n\n**open-mcp-apps** is an open engine built on [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview)\n(`ui://`, `io.modelcontextprotocol/ui`) — an extension to the core Model Context Protocol\nspecification, and [the first official one](https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/),\nlive since 26 January 2026. It gives any MCP-Apps-capable host (Claude Desktop, claude.ai, Codex,\nChatGPT, …) three things the extension itself doesn't provide:\n\n1. **An app registry the AI can write to.** Ask for a UI that doesn't exist — the AI reads\n the authoring guide, writes a single-file HTML app against a tiny `window.oma` API,\n and saves it. From that moment you can open it by name, in this chat and every future one.\n2. **Persistent, versioned data — separate from the UI.** Apps bind to generic\n *collections* of items backed by SQLite plus an append-only `change_event` ledger. Every\n mutation is an idempotent domain command (`command_id`) with optimistic concurrency\n (`expected_version`). The AI and the human edit the same store — the widget is just a view.\n3. **A shell runtime so AI-written apps actually work.** Serving `ui://`, the engine wraps\n the app with the official MCP App bridge, host theming (Claude's design tokens,\n light/dark), and the `window.oma` data API. What you write is a view; the protocol,\n persistence, idempotency and theming are the engine's problem.\n\n**Which of those hosts *this* engine reaches.** It runs on your machine and binds `127.0.0.1`, so it\nserves the hosts on that same machine: Claude Desktop, Claude Code, Codex, plus its own browser\nviewer. A browser host cannot reach a loopback server on your laptop, so **claude.ai and ChatGPT web\nneed a remote deployment** — today that means the hosted [openmcp.app](https://openmcp.app), which\nruns this same engine for you. Running that remote shape *yourself* is on the roadmap and not done.\n\n| | |\n|---|---|\n| **Version** | 0.7.0 ([`CHANGELOG.md`](CHANGELOG.md)) |\n| **License** | MIT, whole repository ([`LICENSE`](LICENSE) · [`LICENSING.md`](LICENSING.md)) |\n| **npm** | `@2nd1st/open-mcp-apps` — **scoped**; the unscoped name is an unrelated package |\n| **Command** | `npx -y @2nd1st/open-mcp-apps` — the line your host's MCP config runs; a stdio server, not something to run by hand (typed into a terminal it just waits, and says so) |\n| **Requires** | Node 22 or newer. `git` too, on the installer path |\n| **Surface** | 33 tools · a built-in App Store · 3 system apps seeded |\n| **Platforms** | macOS · Windows · Linux |\n| **Hosts** | Claude Desktop · Claude Code · Codex · ChatGPT web — see [Host support](#host-support) |\n| **Hosted** | [openmcp.app](https://openmcp.app) — the remote shape, and the way to reach browser hosts (claude.ai, ChatGPT) |\n\n## Install\n\nopen-mcp-apps runs as a local MCP server. First get it **connected** to your host (below); then\n**onboarding happens inside the host, separately** — that's where the AI builds your first app.\n\n### From npm — nothing to clone\n\nIf you are comfortable editing your host's config file, point it at the published package and\nlet `npx` fetch the engine. This path needs only Node 22 — no `git`, and no checkout for you to\nkeep updated. Paste this into your host's MCP server config:\n\n```json\n{\n \"mcpServers\": {\n \"open-mcp-apps\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@2nd1st/open-mcp-apps\"]\n }\n }\n}\n```\n\nTwo things the installer below does that this path does not: it registers the server into every\nhost it finds, and it pre-seeds the built-in system apps (settings, dashboard, App Store) into\nyour store — so on the `npx` path your registry starts empty and your AI installs what it needs\nfrom the App Store on demand, which is fully available either way. Your data lives in the same\nfixed per-user store, so you can move between an `npx` server and a cloned one without migrating\nanything.\n\n> **A note on npm:** this project publishes under the **scoped** name\n> [`@2nd1st/open-mcp-apps`](https://www.npmjs.com/package/@2nd1st/open-mcp-apps). The *unscoped*\n> `open-mcp-apps` on the registry is **not this project** — that name is held by an unrelated\n> package. Check for the `@2nd1st/` prefix; the scope is the only thing telling the two apart.\n\n### With the installer — one command\n\nInstalling needs a shell, so the chat apps (Claude Desktop, Codex) can't install themselves — use\none of these instead:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/2nd1st/open-mcp-apps/main/install.sh | sh\n```\n\nIt opens a short picker to choose which hosts to register into — **Claude Desktop, Claude Code,\nCodex** — plus your permission preference. Skip it with `-s -- --yes`, or target one host with\n`-s -- --host codex`.\n\n**Where it puts the clone**, before you pipe anything into a shell: `~/open-mcp-apps`. Set `OMA_DIR`\nto put it somewhere else — `curl -fsSL | OMA_DIR=~/src/oma sh`. Re-running the one-liner\nupdates that same clone in place instead of making a second one. Your apps and data are *not* in it\n(they live in the per-user store under [Configuration](#configuration)), so the folder is safe to\nmove or delete — and `node uninstall.mjs` does not delete it for you.\n\n**With a coding agent** (Claude Code, Codex CLI — they have a shell), paste:\n\n> Read https://raw.githubusercontent.com/2nd1st/open-mcp-apps/main/install.md and follow it.\n\nEither way, `install.mjs` registers the server into each host you pick, idempotently — it never\nclobbers your other servers, pins a stable `node` launcher (native SQLite ABI), reports what\nchanged, and cleans up a pre-rename entry if one lingers. Your data lives in a **fixed per-user\nstore** (not inside the clone), so every host shares the same apps and data.\n\n### From a clone — for development\n\n```bash\ngit clone https://github.com/2nd1st/open-mcp-apps && cd open-mcp-apps\nnpm install\nnode install.mjs # same picker as the one-liner above\n```\n\nTo wire a clone into a host by hand instead, point it at the checkout — this is the shape\n`install.mjs` writes:\n\n```json\n{\n \"mcpServers\": {\n \"open-mcp-apps\": {\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/open-mcp-apps/src/server.mjs\"]\n }\n }\n}\n```\n\n### Hosted\n\n[openmcp.app](https://openmcp.app) runs the engine for you. The engine in this repository binds\n`127.0.0.1` by design, so a self-hosted remote deployment is not a supported shape yet — see\n[Status and roadmap](#status-and-roadmap).\n\n### Uninstall\n\n`node uninstall.mjs` unregisters the server from every host it finds — but **keeps your data**:\nthe shared store stays put, so re-installing later restores every app and all data. It also leaves\nthe installer's clone (`~/open-mcp-apps`, or wherever `OMA_DIR` pointed) on disk — nothing here ever\ndeletes that folder, so remove it yourself when you want the checkout gone.\n\n```bash\nnode uninstall.mjs # unregister from all detected hosts — keeps your data\nnode uninstall.mjs --purge # also delete the shared store (apps + data), irreversible\nnode uninstall.mjs --check # read-only: show what's registered and what would change\n```\n\n## Requirements\n\n- **Node 22 or newer**, on macOS, Windows or Linux.\n- **`git`** — only on the installer path. The `npx` path above needs neither `git` nor a checkout.\n The installer checks for both and stops with a message rather than half-installing if either is\n missing.\n- **A host that renders `ui://`** if you want widgets *in the conversation*. Terminal hosts (Claude\n Code in a terminal, codex CLI) drive the same data by design and put the UI on a browser screen\n beside the terminal instead — one that can follow along, showing whatever the AI just opened. The\n per-host detail is in [Host support](#host-support).\n- **After installing or updating, fully quit and reopen the host** (Cmd-Q, not just closing the\n window) — it keeps its old server process on the old data until fully quit.\n\n## Configuration\n\nEvery setting is an environment variable, set in the `env` block of your host's MCP server entry:\n\n```json\n{\n \"mcpServers\": {\n \"open-mcp-apps\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@2nd1st/open-mcp-apps\"],\n \"env\": {\n \"OMA_VIEWER\": \"1\",\n \"PORT\": \"8787\",\n \"OMA_DYNAMIC_TOOLS\": \"0\"\n }\n }\n }\n}\n```\n\n| Variable | Default | What it does |\n|---|---|---|\n| `OMA_VIEWER` | `1` | The browser viewer on loopback. `0` doesn't start it at all. |\n| `PORT` | `8787` | Where the viewer listens. |\n| `OMA_DYNAMIC_TOOLS` | `0` | `1` also publishes one `open_` tool per saved app. Off by default because it costs prompt cache — and one approval prompt per app. |\n| `OMA_DB` | per-user store | Path to the SQLite store. Set it to isolate a store. |\n\n**Where your data lives.** The whole store is one SQLite file, `open-mcp-apps.db`, in\n`~/Library/Application Support/open-mcp-apps/` (macOS), `%APPDATA%\\open-mcp-apps\\` (Windows), or\n`$XDG_DATA_HOME` else `~/.local/share/open-mcp-apps/` (Linux). It is outside any clone, which is\nwhy every host shares the same apps and data.\n\n**First-run permissions.** The first few tool calls each show an approval dialog — pick\n**\"Always allow\"**. The tool set is small and stable on purpose: read-only tools generally\nskip approval, and the single `open_app` tool covers opening *every* app (including ones the AI\ncreates later) behind that one grant, so nothing new asks again — on every host the installer\nregisters, with no exceptions any more. From 2026-07-28 to 2026-08-16 there were two: **Claude\nDesktop and Claude Code** were registered with `OMA_DYNAMIC_TOOLS=1`, which routed around a\nchat-surface bridge regression by giving every app its own `open_` tool, at one approval\nprompt per app. Re-measured on Desktop 1.30096.5, that symptom is gone, so the installer no longer\nsets the flag for anybody — [`KNOWN-ISSUES.md`](KNOWN-ISSUES.md) carries both readings.\n**If you installed during that window, your entry still has the flag:** `node install.mjs --check`\nreports it as `stale`, and re-running the installer removes that one key while leaving every other\nenv value you have set exactly where it is.\nYou can also batch approvals in **Settings → Connectors → open-mcp-apps → Tool permissions**.\n\n## Usage\n\n**Start in your host.** Restart it after installing. New here? The engine ships one MCP prompt,\n`get_started`. A host that surfaces prompts lists it as **Get started with open-mcp-apps**; hosts\nthat render prompts as slash commands spell it `/mcp__open-mcp-apps__get_started`. Picking it hands\nthe AI the whole opening move. Not every host surfaces prompts — where yours doesn't, nothing is\nlost, because the prompt is just a sentence you can say yourself: **\"I just installed open-mcp-apps\n— show me how to use it with a couple of examples, and suggest a few apps that fit how I work.\"**\nEither way it looks at what you already have and what the App Store already offers, asks you a\ncouple of questions, and sets up a first app tailored to you. This step is separate from install and lives in the host. Or just ask directly:\n\n- *\"make me a board for what I'm juggling right now\"* → the AI writes it, seeds it, and opens it (persistent)\n- *\"make me a habit tracker\"* → watch it read the guide, write the app, save it, open it\n- close the app, reopen, ask again → everything is still there\n\n### The loop\n\n```\n\"make me a kanban\"\n │\n ▼\nlist_apps ── exists? ──► open_app {app: \"kanban\"} (reuse, instant)\n │ no\n ▼\nget_app_guide ──► AI writes HTML ──► save_app\n │\n ▼\nopen_app {app: \"kanban\"} → rendered inline, themed, persistent — reusable in every future chat\n```\n\nApps accumulate. Each one is single-purpose and independent — a board, a tracker, a\nsplitter — minted for the task in front of you and kept for the next time you need it.\n\n### What it looks like\n\nApps render inline, in the chat you were already having. Ask for one and the AI writes it:\n\n![Codex — asking for a reading tracker; the AI writes it and it renders inline, already holding the three books](.github/screenshots/host-codex.webp)\n\nCome back in another chat — or another host — and it's still there, with your data in it:\n\n![Claude — a new chat opens the same reading list, now eight books long](.github/screenshots/host-claude.webp)\n\nThe built-in App Store — rebuilt in 0.5.0 as a real storefront — ships 22 ready-made apps, with\nworking previews and one-click install:\n\n![The App Store — live previews of ready-made apps](.github/screenshots/app-store.webp)\n\n| | |\n|---|---|\n| ![Companion — an AI character with shared memory](.github/screenshots/companion.webp) | ![Family Week — dinners, chores rotation, shopping and weekend plans](.github/screenshots/family-week.webp) |\n| ![Study Cards — spaced repetition with review heatmap and deck shelf](.github/screenshots/study-cards.webp) | ![Knowledge Cards — a visual library of saved answers](.github/screenshots/knowledge-cards.webp) |\n\nEvery app above is a single HTML file bound to plain data collections — written with the same\n`window.oma` API and authoring guide your AI will use for the apps it builds you.\n\nMultiple widgets in one conversation work fine (habit-streaks + meal-planner side by side).\n\n### The browser viewer, and the port it binds\n\nEvery install runs a small local web server on ****. It is how you *see*\nyour apps outside a chat window — one page per app, the same data your AI is reading — and in a\nterminal host it is the only way to see them at all, so the AI hands you the link when it builds\nor opens something.\n\nIt starts on its own; `OMA_VIEWER` and `PORT` above change that. If the port is already taken by\nanother open-mcp-apps process, that one is already serving the same data and this one just shares\nits address; if it is taken by something else, you get no viewer and no links rather than a link\ninto a stranger's server.\n\n**There is no password on it, and that is deliberate.** The listener is hard-wired to `127.0.0.1`,\nso there is no setting that makes it answer from another machine. Any program on your computer that\ncould reach the port can already open the SQLite file directly — a password would be a lock beside\nan open wall. The one way this reaches the internet is a tunnel you start yourself, which is its own\ndeliberate decision; **while a tunnel is up, treat its URL as a secret**, because it is currently the\nonly thing standing between the internet and your data.\n\n## Host support\n\nLive-tested 2026-07-22; ChatGPT web row updated 2026-07-28. **Both readings predate 0.5.0** — the\nlargest change so far, and later than either date. Apart from the cells that carry their own\n2026-08-16 date, nothing in this table has been re-tested on 0.5.0 or newer; a date says when that\nrow was true, not that it was checked again since.\n\n| Host | Renders widgets | Human clicks widget | AI operates data | Same store |\n|---|---|---|---|---|\n| **Claude Desktop** (local stdio) | ✅ — re-checked 2026-08-16 on 1.30096.5: the universal `open_app` renders in chat without the `OMA_DYNAMIC_TOOLS` workaround that shipped for 1.24012.9 (see KNOWN-ISSUES) | ✅ full loop incl. `sendMessage` reply | ✅ | ✅ |\n| **Browser viewer** (`/view/`) | ✅ | ✅ (no chat attached — `sendMessage` degrades to a notice) | via CLI AI | ✅ |\n| **Codex desktop** (ChatGPT app, `enable_mcp_apps` flag) — tested against a **local** engine; remote not established | ✅ experimental | ◐ updates/toggles from widget clicks work; adds were blocked host-side. The umbrella request [openai/codex#28912](https://github.com/openai/codex/issues/28912) (an `enhancement`: \"make MCP apps work end-to-end in the Codex GUI\") closed as completed on 2026-08-05 — but [#30092](https://github.com/openai/codex/issues/30092), the `bug` matching this exact failure and reproduced there by a third party, was still open on 2026-08-16. Not re-tested here either way, so the cell stays ◐. See KNOWN-ISSUES | ✅ | ✅ |\n| **Claude Code** — in a terminal (`claude mcp`) | — in the chat, by design (text fallback) — but see **[a screen beside the terminal](#a-screen-beside-the-terminal)** | — in the chat | ✅ | ✅ |\n| **Claude Code** — the Code surface inside the Claude app | ✅ live-tested 2026-08-16: an app opened with the universal `open_app` renders inline, the same shape the chat surface gives | not measured on this surface | ✅ | ✅ |\n| **codex CLI / IDE** | — in the chat, by design (text fallback) — but see **[a screen beside the terminal](#a-screen-beside-the-terminal)** | — in the chat | ✅ | ✅ |\n| **ChatGPT web** (Work mode) | ✅ live-tested 2026-07-28 (remote HTTPS) — renders at full height, no clamping; a widget loses its data after a page refresh (mitigation shipped, awaiting live re-test here — see KNOWN-ISSUES) | ✅ a widget button added a row and it stuck | ✅ | ✅ |\n\nEverything rides the MCP Apps bridge, so host fixes upstream (e.g. #28912) benefit this\nproject with zero changes.\n\n**On Claude Code specifically:** it is one product with two surfaces, and only one of them can\ndraw — which is why it takes two rows. In a terminal there is no inline widget surface at all: that\nis architecture rather than a gap, and it is exactly what [a screen beside the\nterminal](#a-screen-beside-the-terminal) is for. The Code surface inside the Claude app has a UI and\nrenders inline; the 2026-08-16 reading there came through the universal `open_app`.\n\n**On Codex specifically:** plugins are registered on the web side, so a locally-installed engine\nis reached as an **MCP server**, not as a plugin — which is the right path for a self-hosted\ninstall anyway. Widget rendering in the ChatGPT desktop app also appears to depend on how you are\nsigned in (we have seen it work under an account sign-in; not yet established under an API key).\n\n### A screen beside the terminal\n\nThose two `—` cells say the **chat** shows text. They do not say there is no UI. Since 0.5.1 the\nengine remembers which app was opened last and pushes that pointer to the viewer on the `/events`\nframe, and an app can place a region — `oma.embed(\"@live\", {into})` — that mounts whatever the AI\nopened last and swaps itself when the AI opens another. The App Store ships one: install **`live`**,\nopen `http://127.0.0.1:8787/view/live` in a window you then leave alone, and the terminal keeps the\nconversation while that screen shows the app. The AI opens or writes from the CLI, the screen\nfollows, and you can click, edit and type into it there. Headless CLI use is what it was built for.\n\n**The cheapest form of \"that screen\" is a browser pane in the same tiled workspace** — one column\nover from the agent, in the window you are already working in. Same machine, no tunnel, no second\ndevice; most modern terminal setups can put a browser next to a shell, and that is all this needs.\nA second monitor is the same idea with more desk, and a screen on another device is the same idea\nagain with the caveat below.\n\nThe costs are real and worth stating plainly. There is still **no widget in the transcript**.\n`sendMessage` degrades to a notice on a standalone page, exactly as in the **Browser viewer** row —\nclicks change data, they do not talk back to the chat. The viewer has to be running (`OMA_VIEWER`,\non by default) with a browser pointed at it; this is not zero-config. And the listener is bound to\n`127.0.0.1`, so \"a spare tablet on the wall\" means *this machine's* screen unless you put up the\ntunnel described above and accept what that section says about it. Inside a chat host the same\nregion deliberately draws a placeholder instead of following anything.\n\n*Described from the code as built, not measured on a host — the live-test dates above cover the\ntable, not this section.*\n\n## Writing an app yourself\n\nThe AI is the usual author, but it isn't the only one — its context window shouldn't be the ceiling\non what an app can be. Build one in your own editor, with your own bundler, and install it:\n\n```bash\nnode install-app.mjs ./my-app.html # yours, full trust — same as an AI-authored app\nnode install-app.mjs ./my-app.html --sandboxed # untrusted: runs behind the runner, no capabilities\nnode install-app.mjs --list # what's installed, and under whose provenance\n\n# a build pipeline's output: a readable template + its bundle, plus the declaration as its own file\nnode install-app.mjs ./ui.html --name my-app --manifest ./manifest.json \\\n --asset ./dist/app.js --asset ./dist/app.css --update\n```\n\nTwo shapes are accepted. **One self-contained HTML document** — no size cap (keep it lean: data\nlives in the collection, source is read in windows) — the engine injects the kit CSS, the host's\ndesign tokens and `window.oma`. Or **a template plus a bundle**: the HTML is a readable mount\npoint that references its own build output (`