Skip to content
Back to search

Muse-Chat-MCP

MCP server + OpenAI-compatible shim to use Meta Muse (muse.ai, Hatch) by driving the real logged-in Chrome.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/duclm1x1--muse-chat-mcp/badge.svg)](/listings/duclm1x1--muse-chat-mcp)

HTML

<a href="/listings/duclm1x1--muse-chat-mcp"><img src="/api/listings/duclm1x1--muse-chat-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/duclm1x1/Muse-Chat-MCP.git
cd Muse-Chat-MCP
npm install

`npm install` only pulls `playwright-core` (a library) — it does **not** download a browser.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 377 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Muse-Chat-MCP
  2. **Use Meta Muse — the [muse.ai](https://muse.ai) "Hatch" agent — from any MCP client or any OpenAI-compatible client, with your own account and quota.**
  3. Muse has no public API: its chat is an **encrypted WebSocket** (`wss://hatch.metaaivm.com/v1/noise`, an X25519 + HKDF + AES‑GCM + Ed25519 *Noise* transport). So instead of re‑implementing the protocol, this project **drives your real, logged‑in Chrome** with Playwright: the app performs all the crypto itself, and we type into the composer and read the rendered reply.
  4. That gives you two front doors:
  5. | Front door | What it is | Use it from |
  6. | --- | --- | --- |
  7. | **MCP server** (stdio) | 7 tools: `muse_status`, `muse_login`, `muse_new_chat`, `muse_chat`, `muse_read_last`, `muse_dump_dom`, `muse_close` | Claude Desktop, opencode, Cursor, any MCP host |
  8. | **OpenAI-compatible shim** (HTTP) | `GET /v1/models`, `POST /v1/chat/completions` (stream + non-stream, tool calling) | any OpenAI SDK / `@ai-sdk/openai-compatible` provider |
  9. Plus a tiny **CLI** (`muse-cli.mjs`) for one-shot generation from scripts.
  10. > [!IMPORTANT]
  11. > This drives **your** browser and **your** Muse account. It ships with **no** credentials, no Chrome profile, and no captured traffic — you sign in to your own Meta account on first run. See [Disclaimer](#disclaimer).
  12. ---
  13. ## Features
  14. - **MCP tools** over stdio — drop-in for Claude Desktop / opencode / any MCP host.
  15. - **OpenAI-compatible HTTP shim** with **real streaming** (SSE), correct `finish_reason`, and `/v1` error objects.
  16. - **Prompt-injected tool calling** — expose OpenAI `tools` to Muse and get `tool_calls` back.
  17. - **Attachments** — send images/video with a prompt (MCP `files`, OpenAI `image_url` parts, CLI `-f`).
  18. - **Sessions & media** — list/open/read/send in any Muse chat, and pull out the images/videos Muse generates (links + download).
  19. - **Muse Manual** — a living guide to Muse's video/image/content capabilities at [`manual/MUSE_MANUAL.md`](manual/MUSE_MANUAL.md), regenerated with `node manual/interview.mjs`.
  20. - **Reuses your existing login** via a dedicated Chrome profile, or attaches to a Chrome you already run with `--remote-debugging-port=9222`.
  21. - **Never kills your browser**: when attached over CDP it only *disconnects* on close.
  22. - **Resilient**: if the profile is locked by a running Chrome, it auto-attaches over CDP instead of failing.
  23. - **Correct streaming**: only stable, monotonic text is emitted, so a rewrite mid-answer never duplicates.
  24. - No browser download — it uses your **installed** Chrome via [`playwright-core`](https://www.npmjs.com/package/playwright-core).
  25. ---
  26. ## Requirements
  27. - **Node.js ≥ 18** (tested on v24).
  28. - **Google Chrome** (or Edge) installed.
  29. - A **Meta account** with access to Muse.
  30. - Windows / macOS / Linux (paths in the examples are Windows; adjust for your OS).
  31. ---
  32. ## Install
  33. ```bash
  34. git clone https://github.com/duclm1x1/Muse-Chat-MCP.git
  35. cd Muse-Chat-MCP
  36. npm install
  37. ```
  38. `npm install` only pulls `playwright-core` (a library) — it does **not** download a browser.
  39. ## First run (log in once)
  40. ```bash
  41. npm run selftest # launches Chrome, prints login/browser state, then closes
  42. ```
  43. A Chrome window opens to `https://muse.ai`. Sign in with your Meta account. The session is stored in a dedicated profile (`.muse-profile/`, git-ignored) and reused afterwards. When `muse_status` reports `"loggedIn": true`, you're ready.
  44. ---
  45. ## Use it as an MCP server
  46. ### opencode
  47. Add to `~/.config/opencode/opencode.jsonc`:
  48. ```jsonc
  49. {
  50. "mcp": {
  51. "muse": {
  52. "type": "local",
  53. "command": ["node", "/absolute/path/to/Muse-Chat-MCP/muse-server.mjs"],
  54. "enabled": true,
  55. "timeout": 300000
  56. }
  57. }
  58. }
  59. ```
  60. > The `timeout` is the **tool-listing** timeout at startup, not per-call — long `muse_chat` calls are fine.
  61. ### Claude Desktop
  62. Add to `claude_desktop_config.json`:
  63. ```json
  64. {
  65. "mcpServers": {
  66. "muse": {
  67. "command": "node",
  68. "args": ["/absolute/path/to/Muse-Chat-MCP/muse-server.mjs"],
  69. "env": { "MUSE_PROFILE_DIR": "/absolute/path/to/Muse-Chat-MCP/.muse-profile" }
  70. }
  71. }
  72. }
  73. ```
  74. ### MCP tools
  75. | Tool | Arguments | Returns |
  76. | --- | --- | --- |
  77. | `muse_status` | – | browser / login / composer state |
  78. | `muse_login` | `timeout_sec?` | waits for Meta sign-in to complete |
  79. | `muse_new_chat` | – | navigates to the home composer |
  80. | `muse_chat` | `prompt`, `timeout_sec?`, `new_thread?`, `files?`, `chat?` | `{ reply, messages, threadUrl, elapsedMs, … }` |
  81. | `muse_read_last` | – | latest assistant message (no send) |
  82. | `muse_chats` | `query?` | list chats (Main chat / Channels / Side chats), optional title filter |
  83. | `muse_open_chat` | `target` | open a chat (title, index, URL, or id) |
  84. | `muse_read_chat` | `chat?`, `max?` | messages of a chat (all roles, with media links) |
  85. | `muse_media` | `chat?`, `download?`, `dir?` | image/video/attachment links from a chat (optionally downloaded) |
  86. | `muse_dump_dom` | `max_chars?` | element counts + transcript HTML (selector debugging) |
  87. | `muse_close` | – | closes the browser (disconnect-only if CDP-attached) |
  88. Typical flow: `muse_status` → (if needed `muse_login`) → `muse_chat { prompt }`.
  89. ### Attachments (images & video)
  90. `muse_chat` accepts a `files` array — absolute paths or URLs — and attaches them to the
  91. message before sending:
  92. ```jsonc
  93. { "name": "muse_chat", "arguments": { "prompt": "What is in this image?", "files": ["C:\\path\\frame.jpg", "https://host/clip.mp4"] } }
  94. ```
  95. Muse accepts images, video and documents (the composer's file input has **no** `accept`
  96. filter). Files are set directly on the hidden composer input — no OS file dialog.
  97. ### Sessions (multiple chats)
  98. Muse has a **Main chat** plus **Channels** and **Side chats** (each a `muse.ai/thread/<id>`).
  99. List them, then target any one for reading or sending:
  100. - **MCP** — `muse_chats`, `muse_open_chat { target }`, `muse_read_chat { chat?, max? }`, and `muse_chat { …, chat }` where the target is a title, index, thread URL, or thread id.
  101. - **HTTP** — `GET /v1/muse/chats` (list) and `GET /v1/muse/chat?target=<name|index|url>&max=100` (read); send with header `x-muse-chat: <name|index|url>` (or body `chat`).
  102. - **CLI** — `--list-chats`, `--read [<chat>]`, `--chat <chat>`.
  103. > Muse can generate images/video **inside a chat** (it replies with share links) — use a
  104. > session read or the media tools to retrieve them.
  105. ### Media (generated images & video)
  106. When asked, Muse makes media and replies with a share link (`https://muse.ai/files/<…>/….mp4|.png`).
  107. Extract and download them:
  108. - **MCP** — `muse_media { chat?, download?, dir? }`.
  109. - **HTTP** — `GET /v1/muse/media?target=<chat>&download=1&dir=<dir>`.
  110. - **CLI** — `--media [<chat>] [--download] [--dir <dir>]`.
  111. Links are public (anyone with the link can view) but expire (~2 days) — download to keep them.
  112. ---
  113. ## Use the OpenAI-compatible shim
  114. `muse-server.mjs` starts the shim automatically on **port 8787** (disable with `MUSE_SHIM_PORT=0`). Run it stand-alone (HTTP only, no MCP) with `node muse-server.mjs --serve-only`.
  115. | Route | Purpose |
  116. | --- | --- |
  117. | `GET /v1/models` | model list |
  118. | `POST /v1/chat/completions` | chat completions (stream + non-stream, tools) |
  119. | `GET /health` | browser / login state |
  120. | `GET /v1/muse/chats` | list Muse chats |
  121. | `GET /v1/muse/chat?target=…` | read a chat (optionally opening it first) |
  122. | `GET /v1/muse/media?target=…` | media links in a chat (add `download=1` to save) |
  123. ```bash
  124. curl http://127.0.0.1:8787/v1/models
  125. curl http://127.0.0.1:8787/v1/chat/completions \
  126. -H "content-type: application/json" \
  127. -d '{"model":"muse-spark-1.3","messages":[{"role":"user","content":"Summarize what Muse is in 2 sentences."}]}'
  128. ```
  129. ### Any OpenAI client
  130. ```python
  131. from openai import OpenAI
  132. client = OpenAI(base_url="http://127.0.0.1:8787/v1", api_key="muse-local")
  133. r = client.chat.completions.create(
  134. model="muse-spark-1.3",
  135. messages=[{"role": "user", "content": "Write a haiku about browsers."}],
  136. stream=True,
  137. )
  138. for chunk in r:
  139. print(chunk.choices[0].delta.content or "", end="")
  140. ```
  141. ### opencode provider
  142. ```jsonc
  143. "provider": {
  144. "muse-local": {
  145. "npm": "@ai-sdk/openai-compatible",
  146. "name": "Muse (local shim)",
  147. "options": { "baseURL": "http://127.0.0.1:8787/v1", "apiKey": "muse-local" },
  148. "models": {
  149. "muse-spark-1.3": { "name": "Muse Spark 1.3" },
  150. "muse": { "name": "Muse" }
  151. }
  152. }
  153. }
  154. ```
  155. ### Shim behavior
  156. - **Real streaming** — DOM text is re-emitted as OpenAI deltas. Only text that is a *monotonic extension* and has been stable for `MUSE_STREAM_QUIET_MS` (default 600 ms) is emitted; the remainder is flushed at the end. Each stream ends with exactly one `finish_reason`, then `[DONE]`.
  157. - **Tools** — prompt-injected. Tool schemas are embedded with a *decision-only* rule ("do not execute"), so Muse returns `{"tool_calls":[{"name","arguments"}]}` instead of trying to actually run the action. Parsed into OpenAI `tool_calls` (`finish_reason: "tool_calls"`). Best-effort, not a native function-calling API.
  158. - **Attachments** — send images/video via OpenAI multimodal content (`{"type":"image_url","image_url":{"url":…}}`) or a top-level `files` array (local paths / URLs / data-URIs). Muse sees them like a normal chat attachment.
  159. - **Plain message** — the shim sends the latest user message **verbatim**: no `### USER/### ASSISTANT` role markers and no "continue the conversation" wrapper. Muse flags roleplay-style wrappers as prompt-injection and refuses them, so the bridge never adds any. Prior context comes from Muse's own thread.
  160. - **Sessions** — target a chat with header `x-muse-chat: <title|index|url>` (or body `chat`); read chats via `GET /v1/muse/chats` and `GET /v1/muse/chat`.
  161. - **Headers** — `x-muse-thread: new` (navigate to `/` first), `x-muse-timeout-ms`.
  162. ---
  163. ## Use the CLI
  164. `muse-cli.mjs` talks to the shim (reusing a running one, or auto-starting `--serve-only` and shutting it down after).
  165. ```bash
  166. node muse-cli.mjs "Explain what a B-tree is in 2 sentences." # streams to stdout
  167. node muse-cli.mjs --no-stream -s "Output ONLY raw code." "Write ..." # exact final code
  168. node muse-cli.mjs -f ./frame.jpg "Write a Facebook caption for this image." # attach image/video
  169. node muse-cli.mjs --list-chats # list Muse chats
  170. node muse-cli.mjs --read "Video creation capability" # read a chat
  171. node muse-cli.mjs --chat "Reply with pong" "hi" # send into a chat
  172. echo "<file>" | node muse-cli.mjs -s "Review this file" # stdin prompt
  173. npm run muse -- "hello" # via package.json
  174. ```
  175. Options: `-s/--system`, `-m/--model`, `-t/--timeout`, `-f/--file <path|url>` (repeatable), `--chat <name|index|url>`, `--list-chats`, `--query <text>`, `--read [<chat>]`, `--media [<chat>]`, `--download`, `--dir <dir>`, `--new-thread`, `--no-stream`, `--json`, `--base` (or env `MUSE_SHIM_URL`).
  176. ---
  177. ## Architecture
  178. ```
  179. MCP client (Claude Desktop / opencode / …) OpenAI client (SDK / opencode provider)
  180. │ stdio (JSON-RPC) │ HTTP /v1/*
  181. ▼ ▼
  182. muse-server.mjs ───────────► muse-openai-shim.mjs ────┘
  183. │ (MCP tools) (SSE + JSON)
  184. └──────────────┬──────────────────────────┘
  185. ▼
  186. muse-driver.mjs playwright-core
  187. ▼
  188. Chrome (dedicated profile ./.muse-profile) ──► https://muse.ai
  189. ```
  190. ### Why a browser driver?
  191. Captured from a real session (endpoints + WS frames), Muse chat is **not** REST/SSE:
  192. | Signal | Value |
  193. | --- | --- |
  194. | App | Next.js on Vercel, fronted by Meta `fwdproxy` |
  195. | Auth | cookie-based: `POST /api/auth/check` → `{ ok, access_token, viewer_id }` |
  196. | Session | `GET /api/session` → assigned VM `wss://<vm_id>.metaaivm.com/` |
  197. | Wake | `POST /api/hatch/vm/wake` |
  198. | Chat transport | WebSocket `wss://hatch.metaaivm.com/v1/noise` — RPC methods `chat.stream`, `chat.history`, `chat.mark_seen` |
  199. | Frames | **encrypted binary** (Noise handshake), signed `auth_token`/`notary_token` in the WS URL |
  200. | `/api/falco` | telemetry only — **not** chat |
  201. So the only robust options are (1) drive the real browser (this project) or (2) re-implement the encrypted Noise client ([roadmap](#roadmap)).
  202. ### Selectors
  203. | Purpose | Selector |
  204. | --- | --- |
  205. | Composer root | `[data-hatch-composer-root]` |
  206. | Editor | `[data-hatch-composer-root] textarea` (fallback `[data-lexical-editor="true"]`) |
  207. | Send | `Enter` key |
  208. | Attach | `[data-hatch-composer-root] input[type="file"]` (hidden; `setInputFiles`) |
  209. | Chat list | `[data-testid="hatch-thread-row"]` |
  210. | Streaming | `[data-testid="hatch-composer-stop-button"]` |
  211. | Messages | `[data-message-item]` with `data-message-role="user" \| "assistant"` |
  212. | Error | `[data-testid="assistant-response-error-notice"]` |
  213. | Auth probe | page-origin `fetch('/api/auth/check', { method: 'POST' })` |
  214. ---
  215. ## Reproduce this yourself (HAR → coding agent)
  216. You don't have to reverse-engineer anything by hand. Capture what the app actually does,
  217. then let a coding agent read it and write the bridge for you.
  218. **Requirements: Google Chrome + some kind of coding agent** — Claude Code, OpenAI Codex,
  219. opencode, Cursor, Cline, Aider, … anything that can read files.
  220. 1. **Open the app.** In Chrome, go to `https://muse.ai` and sign in with **your own** account.
  221. 2. **Open DevTools.** Press `F12` → **Network** tab → tick **Preserve log**. Leave it open for
  222. the whole session so the WebSocket frames get recorded.
  223. 3. **Filter the traffic.** Click **Fetch/XHR** to see the HTTP calls, and **WS** to see the chat
  224. WebSocket. Muse's chat is a **WebSocket**, not a REST call, so you want *both*.
  225. 4. **Send a few prompts** (e.g. `hi`, `what can you do?`) so real traffic is recorded.
  226. 5. **Export a HAR.** Right-click anywhere in the request list → **Save all as HAR with content**.
  227. Pick the version **"with sensitive data"** — the sanitized export strips cookies and
  228. WebSocket frames, which makes the capture useless.
  229. 6. **Hand it to your coding agent.** Drop the file into your project (e.g. `captures/muse.har`)
  230. and give the agent a prompt like this:
  231. ```text
  232. Analyze captures/muse.har from a web chat app and report:
  233. 1) The chat transport: REST/SSE vs WebSocket. List every relevant endpoint
  234. (auth, session, wake, chat) and how authentication works (cookies? tokens?).
  235. 2) The WebSocket: URL, subprotocol, and whether frames are encrypted/binary —
  236. e.g. a Noise handshake (X25519 + HKDF + AES-GCM + Ed25519) — plus the RPC method names.
  237. 3) The most robust way to build a local bridge that exposes this chat as
  238. (a) an MCP tool and (b) an OpenAI-compatible /v1 endpoint, given there is no official API.
  239. ```
  240. The agent will read the HAR and tell you exactly what to build. In our capture it surfaced
  241. `POST /api/auth/check`, `GET /api/session`, `POST /api/hatch/vm/wake`, and the **encrypted**
  242. `wss://hatch.metaaivm.com/v1/noise` WebSocket with a `chat.stream` method — which is precisely
  243. why this project **drives the real browser** instead of calling a REST API. If your agent
  244. reaches the same conclusion, you're spot on.
  245. > [!WARNING]
  246. > A HAR "with sensitive data" contains your **session cookies and access tokens**. Never commit
  247. > it, never paste it into a chat, never share it. This repo's `.gitignore` already blocks `*.har`.
  248. ---
  249. ## Configuration (environment)
  250. | Variable | Default | Meaning |
  251. | --- | --- | --- |
  252. | `MUSE_PROFILE_DIR` | `./.muse-profile` | dedicated Chrome profile (holds your login) |
  253. | `MUSE_URL` | `https://muse.ai/` | app URL |
  254. | `MUSE_CHANNEL` | `chrome` | `chrome` or `msedge` |
  255. | `MUSE_HEADLESS=1` | off | run headless (log in headed first) |
  256. | `MUSE_CDP` | – | attach to an existing Chrome at this URL (e.g. `http://127.0.0.1:9222`) instead of launching |
  257. | `MUSE_STREAM_QUIET_MS` | `600` | streaming stability window (skip mid-message draft rewrites) |
  258. | `MUSE_LAUNCH_TIMEOUT_MS` | `60000` | launch / navigation timeout |
  259. | `MUSE_SHIM_PORT` | `8787` | shim port (`0` disables the shim) |
  260. | `MUSE_SHIM_HOST` | `127.0.0.1` | shim bind host |
  261. | `MUSE_SHIM_TIMEOUT_MS` | `240000` | default shim request timeout |
  262. | `MUSE_SHIM_MODELS` | `muse-spark-1.3,muse-spark-1.3-contributor,muse` | advertised model ids |
  263. | `MUSE_SHIM_URL` | `http://127.0.0.1:8787/v1` | shim base url used by the CLI |
  264. | `MUSE_CLI_AUTOSTART=0` | off | disable the CLI auto-starting a shim |
  265. ---
  266. ## Troubleshooting
  267. - **`loggedIn: false`** → run `muse_login` (or `npm run selftest`) and sign in in the Chrome window.
  268. - **`composerReady: false`** after login → `node muse-server.mjs --dump-dom`; if the DOM changed, re-derive selectors and update `SELECTORS` in `muse-driver.mjs`.
  269. - **Empty reply / `timedOut`** → raise `timeout_sec`; agent tasks (browsing, VM work) can take minutes. `needsApproval: true` means Muse is waiting on an in-app approval you must click.
  270. - **Chrome profile locked** → expected if a Chrome already uses `.muse-profile`. The driver auto-attaches to `http://127.0.0.1:9222` in that case; otherwise close that window, or start Chrome with `--remote-debugging-port=9222` and set `MUSE_CDP`.
  271. - **`npm` blocked in PowerShell** → call `& "C:\Program Files\nodejs\npm.cmd"` instead of `npm`.
  272. ## Limitations
  273. - **One conversation.** Muse is a single persistent thread; the in-app "new chat" control is unreliable. The shim sends the full transcript each call; `x-muse-thread: new` navigates to `/` first (best-effort fresh context).
  274. - **Serialized** — one browser, requests run one at a time (auto-queued).
  275. - **Tool calling is prompt-injected** — best-effort, not a native function-calling API.
  276. - **DOM-driven** — a Muse UI change can break selectors; `muse_dump_dom` is the escape hatch.
  277. ---
  278. ## Roadmap
  279. - [ ] **Phase 2 — headless Noise client.** Talk to Muse directly over `wss://hatch.metaaivm.com/v1/noise` (X25519 + HKDF + AES‑GCM + Ed25519) with a `MUSE_TRANSPORT=noise|browser` switch, keeping the browser driver as fallback.
  280. - [ ] Native tool-calling passthrough for clients that support it.
  281. - [ ] Multi-thread support when Muse exposes a reliable switch.
  282. ## Disclaimer
  283. This is an **unofficial, unaffiliated** tool. It automates *your own* logged-in browser session and does not bundle, proxy, or share anyone's credentials. Use it only with an account you are entitled to use, and respect Muse's / Meta's Terms of Service and your local laws. The maintainers are not responsible for misuse or for any consequences of using this software. There is **no** API key, Chrome profile, or captured traffic in this repository — you bring your own.
  284. ## License
  285. [MIT](LICENSE) © 2026 duclm1x1

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.