collab-md

Real-time collaborative markdown editing with agents and humans through tunneled local servers via MCP.

Setup

Add the MCP server to Claude Code (one-time):

claude mcp add --scope user collab -- npx @eyalronel/collab-md

Auto-approve tools (optional)

On first use, Claude Code will ask you to approve each collab tool. To skip these prompts, select "Yes, and don't ask again" when prompted — or add this to your ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__collab__share_file",
      "mcp__collab__join_session",
      "mcp__collab__stop_session",
      "mcp__collab__set_config",
      "mcp__collab__set_identity",
      "mcp__collab__read_document",
      "mcp__collab__list_blocks",
      "mcp__collab__write_block",
      "mcp__collab__insert_block",
      "mcp__collab__delete_block",
      "mcp__collab__batch_edit",
      "mcp__collab__download_document",
      "mcp__collab__get_history"
    ]
  }
}

Usage

Share a file

Tell your agent:

"Share notes.md for collaboration"

This starts a local server, opens a tunnel, and gives you a shareable URL. The browser opens automatically.

Join a session (started by someone else)

Tell your agent:

"Join collaboration at https://abc123.trycloudflare.com/d/xyz"

The browser opens automatically and editing tools become available.

Stop sharing or leave a session

Tell your agent:

"Stop sharing" or "Leave the session"

This cleanly shuts down the server/tunnel (if hosting) or disconnects from the remote session (if joined).

Edit the document

Your agent can edit through MCP tools (write_block, insert_block, etc.), or you can edit the file directly in your editor — changes sync both ways in real-time.

Configure ngrok (optional)

By default, Cloudflare tunnels are used. To use ngrok instead:

"Set my ngrok token to 2abc123..."

Your agent will call set_config to save it. Ngrok will be used for all future sessions.

How it works

You (Claude Code)                    Collaborator (Claude Code)
     │                                        │
  share_file                              join_session
     │                                        │
  ┌──▼──────────┐                    ┌────────▼────────┐
  │ Local server │◄── tunnel URL ───►│ MCP proxy to    │
  │ Express + WS │    (Cloudflare)   │ remote server   │
  │ Yjs CRDT     │                   └─────────────────┘
  └──────────────┘
     │         │
  auto-save   browser
  to .md      (live view)

• Edits from agents go through MCP tools with author tracking
• Direct file edits are detected via file watcher and synced
• All changes are tracked in history with author attribution
• The browser shows a live-updating view of the document