mcp-socket

Stateful outbound TCP/UDP MCP server for LLMs.

Sockets stay open across tool calls until you close them or they hit the idle timeout. That makes multi-step protocols practical: HTTP/1.x, SMTP, Redis, DNS (UDP), custom text/binary protocols, and more.

See DESIGN.md for the full design.

Install

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Related MCP server: WireMCP

Run

# stdio (default) — typical for MCP clients
mcp-socket

# or
python -m mcp_socket

# HTTP transport
mcp-socket --transport streamable-http --host 127.0.0.1 --port 8000

CLI options

Tools

tcp_connect / udp_send require IP literals. Call resolve_dns first for hostnames.

Private and local destinations are blocked by default (ADDRESS_BLOCKED). Use --allow-private-network for local testing.

Example (TCP HTTP/1.0)

resolve_dns(hostname="example.com")
→ { "ipv4": ["93.184.216.34"], ... }

tcp_connect(address="93.184.216.34", port=80)
→ { "socket_id": "...", "state": "connected" }

tcp_send(socket_id="...", encoding="utf8",
         data="GET / HTTP/1.0\r\nHost: example.com\r\n\r\n")

tcp_recv(socket_id="...", max_bytes=65536, timeout_seconds=5)
→ { "bytes_received": N, "data_base64": "...", "text": "HTTP/1.0 200 ..." }

close_socket(socket_id="...")

Security

Before every connect() / sendto():

• Destination must be a valid IP literal

• Private/local ranges are denied unless --allow-private-network

• Multicast / unspecified / reserved ranges are always denied

No TLS, no listening sockets, no proxy support — higher-level servers can layer those on top.

Develop

pip install -e ".[dev]"
pytest

License

MIT