affinity-mcp-proxy

affinity-mcp-proxy exposes the local Affinity MCP server as an MCP server over stdio.

It is designed for tools that know how to launch MCP servers as local commands, for example:

{
  "mcpServers": {
    "affinity": {
      "command": "pnpm",
      "args": ["dlx", "affinity-mcp-proxy"]
    }
  }
}

What it does

• connects to the local Affinity MCP server over HTTP/SSE

• re-exposes tools/list and tools/call over stdio

• primes execute_script with read_preamble in the same upstream session

• ships a small CLI for diagnostics and direct tool calls

Related MCP server: affinity-mcp-bridge

Status

• first-class target: macOS

• runtime: Node.js 22+

• package manager: pnpm

Other platforms may work, but this package is only validated on macOS in the first release.

Install and run

Preferred ephemeral usage:

pnpm dlx affinity-mcp-proxy

Direct CLI usage:

pnpm dlx --package affinity-mcp-proxy affinity-mcp-proxy-cli list-tools
pnpm dlx --package affinity-mcp-proxy affinity-mcp-proxy-cli call-tool search_sdk_hints '{"query":"text style"}'

Local development:

pnpm install
pnpm test
pnpm dlx . --help
node ./affinity_mcp_proxy.mjs --help

Requirements

• Affinity must be open

• the local Affinity MCP server must be enabled and listening

• Node.js 22 or newer

By default the proxy tries these upstream URLs:

• http://127.0.0.1:6767/sse

• http://127.0.0.1:6767

• http://[::1]:6767/sse

• http://[::1]:6767

Environment variables

• AFFINITY_MCP_URL

  • force a specific upstream MCP URL

• AFFINITY_MCP_CONNECT_TIMEOUT_MS

  • override the connection timeout

• AFFINITY_MCP_DEBUG

  • enable proxy debug logs on stderr

The proxy requires the SDK to be installed through the package dependencies. There is no alternate local SDK fallback.

Commands

Proxy server:

pnpm dlx affinity-mcp-proxy
pnpm dlx affinity-mcp-proxy --help
pnpm dlx affinity-mcp-proxy --version

Diagnostic CLI:

pnpm dlx --package affinity-mcp-proxy affinity-mcp-proxy-cli list-tools
pnpm dlx --package affinity-mcp-proxy affinity-mcp-proxy-cli execute-script-file ./script.js
pnpm dlx --package affinity-mcp-proxy affinity-mcp-proxy-cli render-spread-file DOCUMENT_SESSION_UUID '{"spread_index":2,"out":"/tmp/spread-2.jpg"}'

Troubleshooting

If the proxy exits immediately:

• confirm Affinity is open

• confirm the local MCP endpoint is enabled

• set AFFINITY_MCP_DEBUG=1 to see connection attempts

• if your environment prefers a specific interface, set AFFINITY_MCP_URL explicitly

If text formatting scripts fail inside Affinity with COMMAND_FAILED, make sure the script sets the current spread to the target text node spread before calling doc.formatText(...).