muse-relay-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
An MCP server that exposes your personal Muse at muse.ai as tools for other coding agents — terminal coding agents, IDEs, and other MCP hosts. Questions travel through the muse-relay file relay: the server writes a request file, a polling hook on the Muse side wakes a Muse worker, and the answer comes back as a file that the server returns as the tool result.
Not an official Meta product. Muse personal has no public API and cannot act as an MCP server natively — this bridge is the workaround. Answers come from your personal Muse, with its long-term memory of your projects, not from a raw model API.
Separate project. This server is a standalone project, independent from the Muse Companion VS Code extension. The two share nothing but the relay folder: the extension does not contain this server, and this server does not need the extension — only the relay folders and the Muse-side polling hook (see Requirements).
A real JSON-RPC session against server.js — handshake, tool list, an async question, and its answer arriving through the relay:
Table of Contents
Related MCP server: akasha-mcp
Quick Start
Every step is labelled with its difficulty. If the relay already runs on your machine — for example because you installed the Muse Companion extension first — this is a five-minute job; the only hard part is the one-time relay setup, and most of that is done by Muse itself.
Step | What you get | Difficulty | Time |
Relay check (Part B, step 5) | Confirmation the relay is live and not paused | 🟢 Easy | ~2 min |
| 🟢 Easy — clone + one check command | ~5 min | |
Part B — Set up the relay (only if no relay exists yet) | The one-time relay behind the server | 🔴 Advanced, one-time — any SSH route from Muse to this machine (e.g. reverse SSH tunnel | ~20–30 min |
The | 🟡 Moderate — paste a JSON snippet, restart the host | ~5 min |
The shortest path: relay live → Part A → Part C → restart the host → ask its agent to call ask_muse_start with a test question, then ask_muse_check until the answer arrives.
Not a terminal person? The relay setup is the only steep part — open muse.ai and ask Muse to set up the muse-relay-inbox hook with you. Muse writes the hook and the worker instructions; your part is enabling an SSH route to your machine (Tailscale is optional — any SSH tunnel, reverse SSH ssh -R, VPN, or jump host works).
For AI Agents (Automated Setup)
If an operator gives you (an AI coding agent such as Claude Code, OpenAI Codex CLI, Google Antigravity, VS Code Copilot, Cursor, Windsurf, or Gemini CLI) this repository URL and asks you to install or set it up for them, follow this exact checklist:
Dependencies & Prerequisites (Zero npm packages required):
Runtime required: Node.js
>= 18(node --version) andgit(or downloadserver.jsdirectly).Do NOT run
npm installor any build step —server.jsuses only built-in Node.js modules (fs,os,path,readline).Tailscale is NOT required: the relay only needs any working SSH path from Muse's environment to the relay folder on this machine (e.g. reverse SSH tunnel
ssh -Rvia a VPS/jump host, Cloudflare Tunnel, WireGuard, ZeroTier, Tailscale, or direct IP). Do not install Tailscale unless the operator specifically asks for it.
Clone the repository & create the local relay directories:
Clone
https://github.com/99apps-id/muse-relay-mcp.gitinto a persistent folder (e.g.~/muse-relay-mcpor the operator's preferred directory) and note the absolute path toserver.js.Ensure the three relay directories exist (
~/muse-relay/inbox,~/muse-relay/outbox,~/muse-relay/archive):Windows (PowerShell):
New-Item -ItemType Directory -Force "$env:USERPROFILE\muse-relay\inbox", "$env:USERPROFILE\muse-relay\outbox", "$env:USERPROFILE\muse-relay\archive"macOS / Linux (Bash):
mkdir -p "$HOME/muse-relay/inbox" "$HOME/muse-relay/outbox" "$HOME/muse-relay/archive"
Smoke-test
server.jslocally:Run
node --check server.jsand pipe the JSON-RPCinitialize+tools/listsmoke test from Part A, step 3 intonode server.jsto confirmask_muse,ask_muse_start, andask_muse_checkare listed.
Register
muse-relayin the operator's MCP host config (merge safely — never overwrite existing MCP servers):VS Code (
%APPDATA%\Code\User\mcp.jsonor.vscode/mcp.json): add under top-level"servers"with"type": "stdio","command": "node","args": ["<ABSOLUTE_PATH_TO_SERVER_JS>"].Claude Code: run
claude mcp add muse-relay -- node "<ABSOLUTE_PATH_TO_SERVER_JS>"(or merge into~/.claude.jsonunder"mcpServers").OpenAI Codex CLI (
~/.codex/config.toml): append the TOML table[mcp_servers.muse-relay]withcommand = "node"andargs = ["<ABSOLUTE_PATH_TO_SERVER_JS>"].Google Antigravity (
~/.gemini/antigravity/mcp_config.json), Claude Desktop, Cursor (~/.cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json), Gemini CLI (~/.gemini/settings.json): merge"muse-relay": { "command": "node", "args": ["<ABSOLUTE_PATH_TO_SERVER_JS>"] }under"mcpServers".
Report clearly to the operator:
Tell the operator to restart their IDE / agent session so the new
muse-relayMCP tools load.Check whether
~/muse-relay/control.jsonor~/muse-relay/applied.jsonalready exists:If they exist, the Muse-side SSH relay is already configured — remind the operator to ensure the relay is not paused (
"paused": falseincontrol.json) and that themuse-relay-inboxhook is enabled on muse.ai.If they do not exist yet, inform the operator that the local MCP server and relay folders are ready, and point them to the one-time SSH reachability +
muse-relay-inboxhook setup in Part B.
Tools
Tool | Mode | Behaviour |
| Blocking | Ask a question and wait for the answer in one call (default timeout 600 s, adjustable 5–3600 s via |
| Async | Submit a question and return immediately with a ticket id. |
| Async / Long-Poll | Fetch or wait for a ticket id. If the answer is already in the outbox, returns immediately (0 ms). Otherwise watches the outbox in real time up to |
Shared arguments: prompt (required), workspaceRoot (optional), answerLanguage (en / id).
Blocking vs Async
Instant delivery when Muse is fast: Both
ask_museandask_muse_checkattach an OS filesystem watcher (fs.watch) to the relayoutboxandarchivefolders. Whether Muse takes 8 seconds or 8 minutes, the tool returns within milliseconds of the answer file landing.Blocking (
ask_muse) is simple: the agent asks and waits in a single tool call (up totimeoutSecs, max 3600 s / 1 hour), while sending MCPnotifications/progressheartbeats when requested by the host. If the call reachestimeoutSecsfirst, it returns a non-errorPENDINGresponse containing the ticket id so the agent can seamlessly continue waiting withask_muse_check.Async + Long-Polling (
ask_muse_start+ask_muse_check) is immune to strict MCP host tool-call timeouts (such as 60–120 s limits in Cursor, Codex, or Claude Code). Eachask_muse_checkcall can hold forwaitSecs(default 25 s, or pass e.g.waitSecs: 45/60) so the agent can patiently wait for long tasks without burning dozens of rapid polling turns.
How It Works
MCP host (agent) your machine Muse side
---------------- ------------ -----------
tool call ----> server.js (stdio, this repo)
write req-mcp-<id>.json ----> ~/muse-relay/inbox/
polling hook (SSH tunnel)
wakes a Muse worker
tool result <---- read res-mcp-<id>.json <---- worker answers, archives req
(outbox, then archived)The server is a single dependency-free Node script speaking line-delimited JSON-RPC over stdio, exactly like a regular MCP server. All the latency and queueing live in the relay behind it.
Requirements
Node.js 18 or newer, available as
node.A working muse-relay on the same machine:
Relay folders
~/muse-relay/{inbox,outbox,archive}(Windows:C:\Users\<WINDOWS_USER>\muse-relay\...), overridable with theMUSE_RELAY_DIRenvironment variable.A network path from Claude's environment to this machine. The hook polls the relay folders over SSH, so this machine must be reachable from Claude's side. The reference setup uses Tailscale (install it on both ends, log in with the same account) plus an SSH server on this machine; any equivalent route — LAN, another VPN, a jump host — works just as well. Tailscale itself is not mandatory; SSH reachability is.
A polling hook named
muse-relay-inboxenabled on the Muse side, which wakes a worker for new request files. A reference setup (folders, SSH/Tailscale reachability, the hook, and the worker instructions) is documented in the companion extension's README, Part B.The relay must not be paused (
control.jsonin the relay folder). While paused, every tool refuses fast with aPAUSEDerror.
Throughout this document, replace the placeholders with your own values:
Placeholder | Meaning | Example |
| Folder where you put this project |
|
| Your Windows account name |
|
Installation
Part A — Get the server
Clone this repository (or copy the project folder) to your install directory:
git clone https://github.com/99apps-id/muse-relay-mcp.git muse-relay-mcp cd muse-relay-mcpVerify the script parses and Node is new enough:
node --version # v18 or newer node --check server.js # no output = OKThere is nothing to install — no
npm install, no build step.(Optional smoke test) Pipe a handshake and a tool list into the server:
printf '%s\n%s\n%s\n' \ '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1.0.0"}}}' \ '{"jsonrpc":"2.0","method":"notifications/initialized"}' \ '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \ | node server.jsYou should see two responses, the second listing
ask_muse,ask_muse_start, andask_muse_check.
Part B — Set up the relay (first time) and make sure it is running
The MCP server is only the front door — without a running relay behind it, questions queue forever. If the relay already runs on this machine (for example because you installed the companion extension first), only step 5 applies. If you are starting from this server alone, work through all five steps:
Create the relay folders on this machine (Windows PowerShell):
New-Item -ItemType Directory -Force "$env:USERPROFILE\muse-relay\inbox" New-Item -ItemType Directory -Force "$env:USERPROFILE\muse-relay\outbox" New-Item -ItemType Directory -Force "$env:USERPROFILE\muse-relay\archive"Make this machine reachable from Claude's environment. Install Tailscale on this machine and on the machine Muse runs on (or its jump host) from tailscale.com/download; log in with the same Tailscale account on both ends. Verify with
tailscale status, and note this machine's mesh address viatailscale ip -4— Muse's side needs it as its SSH target. Another VPN, a plain LAN route, or a jump host is equally fine; only SSH reachability matters, Tailscale is simply the reference route.Enable SSH into this machine and install Muse's public key (ask Muse for it in the muse.ai chat). On Windows, in an elevated PowerShell:
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0 Start-Service sshd Set-Service -Name sshd -StartupType AutomaticPlace the key in
C:\Users\<WINDOWS_USER>\.ssh\authorized_keys— one key per line. If<WINDOWS_USER>is an administrator account, Windows OpenSSH readsC:\ProgramData\ssh\administrators_authorized_keysinstead.Create the polling hook on the Muse side. In the muse.ai chat, ask Muse to create an event hook named
muse-relay-inboxthat polls the relay inbox over the SSH path from step 2 every 5 seconds, wakes a worker for each newreq-*.json, and re-wakes a request that stays unanswered for 15 minutes (watchdog, max 2 retries). The worker reads the request, does the work, writesres-<id>.jsonto the outbox, and moves the request to the archive. A fuller reference — exact worker instructions and settings sync — is Part B of the companion extension's README.Confirm it is live: in the muse.ai chat, confirm the
muse-relay-inboxhook is enabled — if it is disabled, questions queue silently and calls time out. Also make sure the relay is not paused (control.jsonin the relay folder; if you use the companion extension, check its panel). Then verify end-to-end in Part C, step 5.
Part C — Register it in your MCP host
Below are ready-to-use configurations for VS Code, Claude Code, Claude Desktop, OpenAI Codex CLI, Google Antigravity, Cursor / Windsurf, and Gemini CLI. On Windows, escape backslashes in JSON paths (C:\\Project\\muse-relay-mcp\\server.js), or use forward slashes (C:/Project/muse-relay-mcp/server.js).
1. VS Code (GitHub Copilot)
VS Code uses the top-level "servers" key in %APPDATA%\Code\User\mcp.json (global) or .vscode/mcp.json (workspace):
{
"servers": {
"muse-relay": {
"type": "stdio",
"command": "node",
"args": ["<INSTALL_DIR>\\server.js"]
}
}
}2. Claude Code (CLI)
Register with a single command:
claude mcp add muse-relay -- node "<INSTALL_DIR>/server.js"Or add to ~/.claude.json (user scope) or .mcp.json (project scope):
{
"mcpServers": {
"muse-relay": {
"command": "node",
"args": ["<INSTALL_DIR>\\server.js"]
}
}
}3. Claude Desktop
Add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
{
"mcpServers": {
"muse-relay": {
"command": "node",
"args": ["<INSTALL_DIR>\\server.js"]
}
}
}4. OpenAI Codex CLI
Codex CLI uses TOML in ~/.codex/config.toml (or %USERPROFILE%\.codex\config.toml on Windows):
[mcp_servers.muse-relay]
command = "node"
args = ["<INSTALL_DIR>/server.js"](Optional) If your relay folder is custom, add env = { MUSE_RELAY_DIR = "D:/path/to/muse-relay" } under [mcp_servers.muse-relay].
5. Google Antigravity
Add to %USERPROFILE%\.gemini\antigravity\mcp_config.json:
{
"mcpServers": {
"muse-relay": {
"command": "node",
"args": ["<INSTALL_DIR>\\server.js"]
}
}
}6. Cursor, Windsurf, Cline, Gemini CLI & Other MCP Hosts
Most other MCP hosts (~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, ~/.gemini/settings.json, termigo, ODON) use the standard "mcpServers" schema:
{
"mcpServers": {
"muse-relay": {
"command": "node",
"args": ["<INSTALL_DIR>\\server.js"]
}
}
}Custom Relay Folder (MUSE_RELAY_DIR)
If your relay folder is not the default ~/muse-relay, pass MUSE_RELAY_DIR via "env":
{
"command": "node",
"args": ["<INSTALL_DIR>\\server.js"],
"env": {
"MUSE_RELAY_DIR": "D:\\path\\to\\muse-relay"
}
}Restart & Verify
Restart the host app or start a new session — MCP hosts read their server list at startup, so the new tools appear only afterwards.
Verify end-to-end: ask the host's agent to call
ask_muse_startwith a question only your personal Muse can answer (something about your own projects or earlier decisions), thenask_muse_checkuntil the answer arrives. As soon as Muse finishes,ask_muse_checkreturns immediately.
Usage
Prefer the async pair for coding agents:
ask_muse_start, keep working, thenask_muse_checkevery so often.Use blocking
ask_musefor quick questions from hosts with generous tool-call timeouts. If it times out, take the ticket id from the response and continue withask_muse_check— the question stays alive.Each call is a one-shot question, not a conversation thread: include the context the question needs in
prompt(andworkspaceRootwhen relevant). Follow-up questions are new calls.Answers typically take 1–10 minutes (relay polling + a serial worker queue + the work itself). The relay watchdog re-wakes a request that stays unanswered for 15 minutes, at most 2 times.
Use Cases
The point of the bridge is that the answer comes from your personal Muse — with its connected accounts, its own tools, and its long-term memory of your projects — not from a raw model that can only see the current workspace. Four patterns from real use:
1. Pull your Instagram or Threads into the coding chat
Building a content tool, a landing page, or a social dashboard, and the data you need lives in your social accounts? Let the coding agent ask Muse instead of copy-pasting between apps:
ask_muse_start: "Fetch my 10 most recent Instagram posts with their like and
comment counts, and summarize what performed best this week."
ask_muse_start: "Read my Threads direct messages from the last 3 days, group
them by topic, and list anything that still needs a reply."Muse reads the connected account, does the summarizing, and the result lands as a tool result inside the chat UI of your coding app — VS Code, Claude Code, Antigravity, a terminal agent — right next to the code it is relevant to. This needs the account connected to your Muse; Muse reads only what the prompt asks for.
2. Post to Instagram or Threads without leaving the editor
The same path works in the other direction. The coding agent composes the request, Muse does the publishing:
ask_muse: "Draft a short announcement for the v0.2 release (notes attached in
the prompt) and post it to my Threads and Instagram."Muse prepares the draft and shows you the exact text for approval in its own chat before anything is posted — a coding agent's say-so is never enough to publish under your name. Once you approve, Muse posts it and the confirmation comes back through the relay into the coding chat.
3. Delegate a long, web-heavy errand to a Muse worker — a real run
On 19 Nov 2026, an Antigravity agent (Opus 5.5) delegated a multi-step audit to a Muse worker through this bridge: find CCTV streams for three cities for a streaming-directory project, validate that every stream really plays, update the allowlist and the data file. The agent kept working locally; the Muse worker did the web research and validation.
4. Borrow Muse's memory of your other projects
A coding agent sees one workspace. Your Muse remembers the decisions, preferences, and history across all of them:
ask_muse: "In my other terminal-agent project, why did we pin the parser
library to a single version last month — and does that apply here?"Second opinions, cross-project context, "what did I decide about X" — questions no amount of grepping the current repo can answer.
Configuration
Setting | Where | Default | Notes |
Relay folder |
|
| Must match the folder the hook and panel use |
Blocking timeout |
| 600 (range 5–3600) | Timeout never cancels the question; returns ticket id for |
Long-poll wait per check |
| 25 (range 0–600) | Returns immediately when answer arrives; returns |
Answer language |
|
| Sent with each request; the worker answers in this language |
Relay Protocol
Requests are files named req-<ticket>.json in the relay inbox; the ticket id is the file id (mcp-…):
{
"id": "mcp-mwn78gdy9yvl2",
"createdAt": "2026-11-19T06:58:41.000Z",
"prompt": "What did the watchdog change in the relay hook?",
"answerLanguage": "en",
"workspaceRoot": null,
"source": "mcp"
}Answers are res-<ticket>.json in the outbox ({ "id", "answeredAt", "answer" }). ask_muse_check looks in the outbox first, then the archive (the VS Code panel may archive a response before you check), and moves an outbox answer to the archive after returning it. source: "mcp" distinguishes bridge requests from panel requests (source: "panel").
Security and Privacy
The server makes no network calls and collects nothing; it only reads and writes JSON files in the relay folder on your own machine.
Any local process that can write to the relay inbox can ask your Muse questions — treat the relay folder as trusted local state, and keep the Muse-side worker rule: no irreversible actions (git pushes, deletions) unless the prompt explicitly asks.
Never publish your real infrastructure details (hostnames, IPs, usernames) in a fork of this README — use the placeholders.
Limitations
Latency is minutes, not seconds; there is no streaming.
One worker lane on the Muse side: simultaneous questions are answered one at a time, in order. A single worker execution is capped at about 10 minutes by the platform; the watchdog covers failures after that.
One-shot Q&A only — no multi-turn session state is kept by the server.
Troubleshooting
Symptom | Likely cause | Fix |
Tool returns | Relay paused (panel or | Resume the relay in the VS Code panel, or set |
| Muse-side hook disabled | Enable the |
First install, nothing ever answers | Relay prerequisite not set up yet (folders, SSH reachability, hook) | Work through Part B steps 1–4 |
Blocking call times out | Normal for long answers | Use the returned ticket with |
Host does not list the tools | Hosts load MCP config at startup | Restart the app or start a new session; re-check the JSON for trailing commas |
Server fails to start |
| Use the absolute path to the Node binary as |
Answers land in the panel but not the tool | Relay folder mismatch | Make sure |
Changelog
0.1.1
Instant delivery via
fs.watch—ask_museandask_muse_checkwatchoutbox/andarchive/with OS filesystem events so answers return within milliseconds of Muse finishingLong-polling on
ask_muse_check(waitSecs) — waits up towaitSecs(default 25 s, range 0–600 s) before returningPENDING, letting coding agents wait for long tasks without hitting host tool-call timeouts or burning rapid poll turnsSoft
PENDINGtimeout onask_muse+ MCP progress heartbeats —timeoutSecsnow extends up to 3600 s, emitsnotifications/progresswhen aprogressTokenis supplied, and returns a non-errorPENDINGmessage with the ticket id on timeoutRelay safety & cross-agent compatibility — atomic request file writes (
.tmp-req-*.json→ rename), 10 s grace period for in-flight SSH partial response writes, ticket ID path-traversal validation,notifications/cancelledsupport, clean shutdown on stdio close, MCP toolannotations(readOnlyHint,idempotentHint, etc.),additionalProperties: falsefor strict schemas, and ready-to-paste setup guides for VS Code, Claude Code, Claude Desktop, OpenAI Codex CLI (TOML), Google Antigravity, Cursor, Windsurf, and Gemini CLI
0.1.0 — first public release
Three tools:
ask_muse(blocking, ticket survives timeout),ask_muse_start,ask_muse_checkFast
PAUSEDrefusal while the relay is pausedOutbox-then-archive answer lookup; answers archived after delivery
Zero dependencies; single-file Node stdio server
License
Apache License 2.0 — see the LICENSE file in this repository. Attribution notices live in the NOTICE file; redistributions must preserve them (Apache License, Section 4(d)).
Unofficial project. Muse and muse.ai are products of Meta; this server is not affiliated with or endorsed by Meta.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Shared memory for your AI tools: tasks, notes and context every tool can read and write over MCP.
Shared AI memory. ChatGPT, Claude, Cursor and any MCP app read and write the same memory.
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables file-based agent-to-agent communication between Claude Code instances on the same machine, using MCP channels and plain JSON files.5 npm15MIT
- AlicenseNot gradedqualityBmaintenanceGives coding agents a persistent memory by searching a local, read-only index of existing markdown and letting them write findings back as notes that the next session can retrieve. It serves ranked, context-sized results over MCP, injects standing conventions at session start, and keeps data on your machine with secret redaction and archive-only deletion.111 PyPIMIT
- FlicenseNot gradedqualityAmaintenanceEnables AI coding agents to read and write persistent, local-first memory through MCP, storing decisions, preferences, and error patterns per project while surfacing cross-project guidelines, with semantic search over on-disk SQLite and an optional queue for autonomous task execution.-
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to save task insights as atomic markdown cards with bidirectional links and recall relevant ones in later sessions. It shares memory across MCP clients through plain files that can be synced with git.9 npmISC