Merlin Project MCP Extension

Read-only MCP access to the project documents open in Merlin Projecton your Mac, packaged as a Claude Desktop Extension (.mcpb).

Ask about your plan, search activities, resources, assignments, risks, issues and attachments,and pull cost, work or earned-value figures over any date range — without leaving Merlin Project.The extension only ever reads: it never changes, saves or deletes anything in your documents. Youchoose which open document Claude may see at the start of each chat, via the MCP access popoverin Merlin Project's toolbar.

Requirements

macOS
Merlin Project installed, running, and with MCP accessenabled for the document you want Claude to read
Node.js 18 or newer (Claude Desktop supplies its own runtime)

Install

Build the extension archive from source, then open the resulting MerlinProject.mcpb withClaude Desktop, which will offer to install it:

npm install
npm run pack        # writes MerlinProject.mcpb

Merlin Project does not need to be running when you install the extension — Claude will see thefull tool list either way, and connects to the app as soon as it is launched.

How it works

Merlin Project is sandboxed and runs its MCP server inside the app, listening on a Unix domainsocket in its App Group container. This extension is the bridge between that socket and thestdio transport Claude Desktop speaks:

Claude  ⇄  stdio  ⇄  extension server  ⇄  extension client (cached)  ⇄  socket  ⇄  Merlin Project

tools/list / resources/list are answered locally from server/catalog.json, so Claude seesthe full tool metadata even when Merlin Project isn't running.
tools/call / resources/read are forwarded to the live in-app server over the socket at~/Library/Group Containers/9R6P9VZV27.net.projectwizards.merlinproject.mcp/mcp.sock(overridable via MERLIN_MCP_SOCKET for testing).
When Merlin Project isn't reachable, tool calls return a structured "not running" messagetelling the agent to ask you to launch the app. The extension retries the connect on everycall, so it picks up the running app on the next request — no restart of Claude needed. Itdeliberately never launches Merlin Project by itself.
The extension advertises the live server's identity when Merlin Project is up at session start,and forwards the agent's real clientInfo on the socket handshake, so the app's connected-toolspopover shows "Claude" rather than the extension.

The tools themselves — list_open_documents, set_current_document, get_schema_types,get_objects, find_objects, count_objects, list_related, get_media andget_time_phased_values — are implemented inside Merlin Project, not here. This repositorycontains only the bridge.

A Swift build of the same bridge ships with Merlin Project for use outside Claude Desktop. Thetwo are behavior-identical and are kept in sync; the file headers here name their Swiftcounterparts. Unlike the Swift build, this one holds no App Group entitlement and simplyconstructs the container path directly, which works for unsandboxed processes.

Files

manifest.json — MCPB manifest (server.type: "node").
server/index.js — entry point; stdio-facing MCP server.
server/bridge.js — connection cache, socket transport, forwarding logic.
server/catalog.json — generated snapshot of the live server's tools/list /resources/list. Do not edit by hand.
scripts/generate-catalog.js — regenerates server/catalog.json from a running build.
scripts/test-e2e.js — end-to-end tests (live forwarding, app-down fallback, mid-sessionrecovery).

Development

npm install                  # once, and after dependency changes
npm run generate-catalog     # after the app's tool metadata changes; needs Merlin Project running
npm test                     # phase A needs Merlin Project running; B and C are self-contained
npm run pack                 # builds MerlinProject.mcpb

Merlin Project itself is the single source of truth for tool and resource metadata:server/catalog.json is generated by asking a running app for its tools/list andresources/list and snapshotting the responses verbatim. It is committed so that packaging theextension needs no running app. Regenerate it and re-pack whenever the app's tool metadatachanges.

License

MIT — see LICENSE.

Merlin Project MCP Extension