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

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(...).

MCP Servers