mcp-remote-py

Minimal MCP STDIO ↔ Remote SSE proxy in Python.

This project is a deliberately small reimplementation of the core idea from mcp-remote:

• Local side: MCP over STDIO (newline-delimited JSON / JSONL)

• Remote side: MCP over SSE (receives JSON-RPC via SSE message events)

• Send path: remote provides an endpoint SSE event; subsequent client→server messages are sent via HTTP POST to that endpoint.

What this is / isn’t

Included

• Bidirectional proxying of MCP JSON-RPC messages

• No stdout contamination (logs go to stderr)

• Optional custom headers (--header 'Name: value')

Intentionally excluded (keep it simple)

• OAuth / authorization flows

• Token storage / refresh

• Multi-instance coordination / lockfiles

• HTTP↔SSE fallback strategies

Install

Option A — “Global” install with uv (recommended)

Installs a user-scoped executable into ~/.local/bin (macOS/Linux) or %USERPROFILE%\.local\bin (Windows).

Windows (CMD):

Uninstall:

Windows (CMD):

If your shell can’t find the command, ensure ~/.local/bin is on your PATH.

Option B — Dev install (editable)

Run

Transport strategy (Node mcp-remote와 유사):

Custom headers:

MCP client configs (copy/paste)

Codex (~/.codex/config.toml)

Codex expects TOML like this:

If you installed via uv into ~/.local/bin, command is typically:

Claude Desktop (claude_desktop_config.json)

Cursor (~/.cursor/mcp.json)

Windsurf (~/.codeium/windsurf/mcp_config.json)

Troubleshooting

• Nothing works / random parse errors: ensure the remote SSE server emits JSON-RPC only on the default message event. Non-protocol events are ignored.

• Don’t see the command: add ~/.local/bin to PATH (macOS zsh: ~/.zprofile is a good default).

• Logs: all logs go to stderr by design; stdout is reserved for MCP protocol.