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

chmod +x ./*.sh
./install-global-uv.sh

Windows (CMD):

install-global-uv.cmd

Uninstall:

./uninstall-global-uv.sh

Windows (CMD):

uninstall-global-uv.cmd

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

Option B — Dev install (editable)

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .

Run

mcp-remote-py http://127.0.0.1:8080/mcp/sse

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

# default: http-first
mcp-remote-py http://127.0.0.1:8080/mcp/sse --transport http-first

# force SSE-only (서버가 HTTP transport를 지원하지 않을 때)
mcp-remote-py http://127.0.0.1:8080/mcp/sse --transport sse-only

Custom headers:

mcp-remote-py http://127.0.0.1:8080/mcp/sse \
	--header 'Authorization: Bearer TOKEN'

MCP client configs (copy/paste)

Codex (~/.codex/config.toml)

Codex expects TOML like this:

[mcp_servers.ida-remote]
command = "/Users/<you>/.local/bin/mcp-remote-py"
args = ["http://127.0.0.1:8080/mcp/sse"]

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

command = "/Users/<you>/.local/bin/mcp-remote-py"

Claude Desktop (claude_desktop_config.json)

{
	"mcpServers": {
		"ida-remote": {
			"command": "mcp-remote-py",
			"args": ["http://127.0.0.1:8080/mcp/sse"]
		}
	}
}

Cursor (~/.cursor/mcp.json)

{
	"mcpServers": {
		"ida-remote": {
			"command": "mcp-remote-py",
			"args": ["http://127.0.0.1:8080/mcp/sse"]
		}
	}
}

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

{
	"mcpServers": {
		"ida-remote": {
			"command": "mcp-remote-py",
			"args": ["http://127.0.0.1:8080/mcp/sse"]
		}
	}
}

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.