Skip to main content
Glama

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

Part A — Get the server

server.js on your machine — no build, no npm install

🟢 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 ssh -R, jump host, Tailscale/WireGuard, or direct IP) + SSH key; the polling hook is created by Muse on request

~20–30 min

Part C — Register it in your MCP host

The ask_muse tools in your agent

🟡 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:

  1. Dependencies & Prerequisites (Zero npm packages required):

    • Runtime required: Node.js >= 18 (node --version) and git (or download server.js directly).

    • Do NOT run npm install or any build step — server.js uses 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 -R via a VPS/jump host, Cloudflare Tunnel, WireGuard, ZeroTier, Tailscale, or direct IP). Do not install Tailscale unless the operator specifically asks for it.

  2. Clone the repository & create the local relay directories:

    • Clone https://github.com/99apps-id/muse-relay-mcp.git into a persistent folder (e.g. ~/muse-relay-mcp or the operator's preferred directory) and note the absolute path to server.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"
  3. Smoke-test server.js locally:

    • Run node --check server.js and pipe the JSON-RPC initialize + tools/list smoke test from Part A, step 3 into node server.js to confirm ask_muse, ask_muse_start, and ask_muse_check are listed.

  4. Register muse-relay in the operator's MCP host config (merge safely — never overwrite existing MCP servers):

    • VS Code (%APPDATA%\Code\User\mcp.json or .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.json under "mcpServers").

    • OpenAI Codex CLI (~/.codex/config.toml): append the TOML table [mcp_servers.muse-relay] with command = "node" and args = ["<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".

  5. Report clearly to the operator:

    • Tell the operator to restart their IDE / agent session so the new muse-relay MCP tools load.

    • Check whether ~/muse-relay/control.json or ~/muse-relay/applied.json already exists:

      • If they exist, the Muse-side SSH relay is already configured — remind the operator to ensure the relay is not paused ("paused": false in control.json) and that the muse-relay-inbox hook 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-inbox hook setup in Part B.

Tools

Tool

Mode

Behaviour

ask_muse

Blocking

Ask a question and wait for the answer in one call (default timeout 600 s, adjustable 5–3600 s via timeoutSecs). Uses filesystem event watchers (fs.watch) so the answer returns immediately the instant Muse finishes. On timeout the question is not cancelled — you receive a PENDING result with the ticket id to continue waiting via ask_muse_check.

ask_muse_start

Async

Submit a question and return immediately with a ticket id.

ask_muse_check

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 waitSecs (default 25 s, configurable 0–600 s), returning the instant Muse finishes or PENDING if still working. Safe to call repeatedly.

Shared arguments: prompt (required), workspaceRoot (optional), answerLanguage (en / id).

Blocking vs Async

  • Instant delivery when Muse is fast: Both ask_muse and ask_muse_check attach an OS filesystem watcher (fs.watch) to the relay outbox and archive folders. 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 to timeoutSecs, max 3600 s / 1 hour), while sending MCP notifications/progress heartbeats when requested by the host. If the call reaches timeoutSecs first, it returns a non-error PENDING response containing the ticket id so the agent can seamlessly continue waiting with ask_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). Each ask_muse_check call can hold for waitSecs (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 the MUSE_RELAY_DIR environment 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-inbox enabled 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.json in the relay folder). While paused, every tool refuses fast with a PAUSED error.

Throughout this document, replace the placeholders with your own values:

Placeholder

Meaning

Example

<INSTALL_DIR>

Folder where you put this project

C:\Project\muse-relay-mcp

<WINDOWS_USER>

Your Windows account name

alice

Installation

Part A — Get the server

  1. 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-mcp
  2. Verify the script parses and Node is new enough:

    node --version          # v18 or newer
    node --check server.js  # no output = OK

    There is nothing to install — no npm install, no build step.

  3. (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.js

    You should see two responses, the second listing ask_muse, ask_muse_start, and ask_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:

  1. 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"
  2. 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 via tailscale 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.

  3. 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 Automatic

    Place the key in C:\Users\<WINDOWS_USER>\.ssh\authorized_keys — one key per line. If <WINDOWS_USER> is an administrator account, Windows OpenSSH reads C:\ProgramData\ssh\administrators_authorized_keys instead.

  4. Create the polling hook on the Muse side. In the muse.ai chat, ask Muse to create an event hook named muse-relay-inbox that polls the relay inbox over the SSH path from step 2 every 5 seconds, wakes a worker for each new req-*.json, and re-wakes a request that stays unanswered for 15 minutes (watchdog, max 2 retries). The worker reads the request, does the work, writes res-<id>.json to 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.

  5. Confirm it is live: in the muse.ai chat, confirm the muse-relay-inbox hook is enabled — if it is disabled, questions queue silently and calls time out. Also make sure the relay is not paused (control.json in 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

  1. Restart the host app or start a new session — MCP hosts read their server list at startup, so the new tools appear only afterwards.

  2. Verify end-to-end: ask the host's agent to call ask_muse_start with a question only your personal Muse can answer (something about your own projects or earlier decisions), then ask_muse_check until the answer arrives. As soon as Muse finishes, ask_muse_check returns immediately.

Usage

  • Prefer the async pair for coding agents: ask_muse_start, keep working, then ask_muse_check every so often.

  • Use blocking ask_muse for quick questions from hosts with generous tool-call timeouts. If it times out, take the ticket id from the response and continue with ask_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 (and workspaceRoot when 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

MUSE_RELAY_DIR env var

%USERPROFILE%\muse-relay (Windows) / ~/muse-relay

Must match the folder the hook and panel use

Blocking timeout

timeoutSecs argument of ask_muse

600 (range 5–3600)

Timeout never cancels the question; returns ticket id for ask_muse_check

Long-poll wait per check

waitSecs argument of ask_muse_check

25 (range 0–600)

Returns immediately when answer arrives; returns PENDING after waitSecs

Answer language

answerLanguage argument

id

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 PAUSED immediately

Relay paused (panel or control.json)

Resume the relay in the VS Code panel, or set "paused": false in control.json

ask_muse_check stays PENDING forever

Muse-side hook disabled

Enable the muse-relay-inbox hook in the muse.ai chat; queued questions are answered once it runs

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 ask_muse_check, or switch to the async pair

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

node not on PATH for the host

Use the absolute path to the Node binary as command

Answers land in the panel but not the tool

Relay folder mismatch

Make sure MUSE_RELAY_DIR matches the folder the hook/panel actually use

Changelog

0.1.1

  • Instant delivery via fs.watch — ask_muse and ask_muse_check watch outbox/ and archive/ with OS filesystem events so answers return within milliseconds of Muse finishing

  • Long-polling on ask_muse_check (waitSecs) — waits up to waitSecs (default 25 s, range 0–600 s) before returning PENDING, letting coding agents wait for long tasks without hitting host tool-call timeouts or burning rapid poll turns

  • Soft PENDING timeout on ask_muse + MCP progress heartbeats — timeoutSecs now extends up to 3600 s, emits notifications/progress when a progressToken is supplied, and returns a non-error PENDING message with the ticket id on timeout

  • Relay 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/cancelled support, clean shutdown on stdio close, MCP tool annotations (readOnlyHint, idempotentHint, etc.), additionalProperties: false for 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_check

  • Fast PAUSED refusal while the relay is paused

  • Outbox-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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables file-based agent-to-agent communication between Claude Code instances on the same machine, using MCP channels and plain JSON files.
      5 npm
      15
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Gives 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 PyPI
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      ISC