# 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

```sh
# 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

```json
{
  "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