English | 简体中文
An MCP (Model Context Protocol) server that manages WebSocket Reflector X (wsrx) tunnels.
The ret2shell CTF platform exposes dynamic challenge instances only through WebSocket traffic links such as:
wss://ctf.example.com/api/traffic/<token>?port=9999
Platforms that hand out plain host:port pairs can be reached with nc / pwntools directly; these links cannot.
wsrx bridges a WebSocket endpoint to a local TCP port; wsrx-mcp then wraps starting, inspecting, and closing tunnels as MCP tools, so your MCP client (Claude Desktop, Codex, etc.) can call them directly — no manual terminal work.
┌───────────────┐ TCP ┌──────────────┐ WSS ┌───────────────────┐
│ nc / pwntools ├─────────►│ wsrx connect ├─────────►│ platform instance │
└───────────────┘ :1337 └──────────────┘ wss link └───────────────────┘
managed by wsrx-mcp (MCP tools)
| Tool | Description |
|---|---|
wsrx_connect(remote, local_port?, wait?) |
Forward a local TCP port to a ws:///wss:// URL. For the same remote, an existing tunnel is reused; a free port is picked automatically when not specified; by default the call returns only once the local port is actually connectable. |
wsrx_list() |
List tunnels: remote, local port, endpoint, PID, alive. |
wsrx_disconnect(local_port? | remote?) |
Close a tunnel by its local port or remote URL. |
wsrx_stop_all() |
Close every tunnel. |
wsrx_doctor() |
Check the wsrx binary is on PATH and list current tunnels. |
- Python 3.10+
- The
wsrxCLI (releases) installed and on PATH, or setWSRX_BINARYto its location.
Run directly from GitHub with uvx (recommended — no clone needed):
{
"mcpServers": {
"wsrx": {
"command": "uvx",
"args": ["--from", "git+https://github.com/springbot2025/wsrx-mcp", "wsrx-mcp"]
}
}
}Or install once, then point your MCP client at the wsrx-mcp command:
pipx install git+https://github.com/springbot2025/wsrx-mcp{
"mcpServers": {
"wsrx": { "command": "wsrx-mcp" }
}
}| Variable | Default | Description |
|---|---|---|
WSRX_BINARY |
wsrx |
Path/resolved name of the wsrx executable. |
WSRX_MCP_BIND_HOST |
127.0.0.1 |
Address tunnels bind to. Use 0.0.0.0 only if other hosts must reach the tunnels. |
WSRX_MCP_STARTUP_TIMEOUT |
15 |
How long to wait for the local port to become connectable, in seconds. |
Ask your agent:
Connect to wss://ctf.example.com/api/traffic/abc123?port=9999 (the wsrx link from the ret2shell platform) and tell me the local endpoint.
The agent calls wsrx_connect, gets back {"endpoint": "127.0.0.1:54321", ...}, and can then run nc 127.0.0.1 54321 or use pwntools to connect. The same tunnel is reused across calls, and all tunnels close when the service exits.
- Tunnels bind to
127.0.0.1by default. - The server manages subprocesses and holds no credentials — traffic tokens live in the URLs you pass in.
- Only
ws://andwss://remotes are accepted.
pip install -e . pytest
pytestThe tunnel core (wsrx_mcp.manager) has no MCP dependency and is fully injectable for testing.
MIT