mcp-akiko-proxy

MCP stdio proxy over SSH, exposing remote MCP servers (bound to localhost on a remote machine) as tools on the local machine.

Establishes SSH tunnels using your existing ~/.ssh/config host alias, connects to the remote MCP servers over streamable-http through the tunnel, and exposes their tools aggregated behind one local stdio MCP server.

Default targets (configurable):

name	local port	remote url	exposes
blender	8001	http://127.0.0.1:8001/	Blender MCP (blender-mcp daemon on the remote)
qgis	8000	http://127.0.0.1:8000/mcp	QGIS MCP (qgis-mcp daemon on the remote)

Graceful degradation

If the tunnel is down or a backend is unreachable, that backend's tools vanish from tools/list (or their calls return a clear error). The proxy keeps running and retries periodically — it never crashes because a backend is missing.

Usage

# run (stdio; opencode/claude/any MCP client will spawn it):
npx -y github:gbastkowski/mcp-proxy
# or clone + npm install + npm start

Configuration (env vars)

var	default	purpose
MCP_PROXY_HOST	akiko	ssh host alias from ~/.ssh/config
MCP_PROXY_TUNNELS	blender+qgis defaults	JSON [{ name, localPort, remotePort, url }]
MCP_PROXY_TUNNEL_RETRY_MS	15000	reconnect/retry interval for dead backends
MCP_PROXY_CONNECT_TIMEOUT_MS	10000	wait for a tunnel/backend port
MCP_PROXY_SSH_TIMEOUT_MS	5000	ssh ConnectTimeout
MCP_PROXY_NO_TUNNEL	unset	truthy: skip ssh, talk to localhost directly (testing)

Example: opencode on a Macbook using Blender+QGIS on the akiko box

{
  "mcp": {
    "akiko": {
      "type": "local",
      "command": ["npx", "-y", "github:gbastkowski/mcp-proxy"]
    }
  }
}

Run MCP_PROXY_HOST=akiko npx -y github:gbastkowski/mcp-proxy — the host is read from your normal ssh config, keys from your agent.

Requirements

• Node >= 18
• ssh with a configured host alias for the remote machine + working key auth
• On the remote: the target MCP servers bound to 127.0.0.1 (they are not exposed to the network; the SSH tunnel is the only bridge)

License

MIT