Skip to main content
Glama
Sign In
mcp-socket

mcp-socket

by cinit
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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

Option

Default

Description

--transport

stdio

stdio, streamable-http, or sse

--host

127.0.0.1

HTTP bind address

--port

8000

HTTP bind port

--socket-idle-timeout

300

Idle seconds before auto-close

--cleanup-interval

5

Cleanup scan interval

--allow-private-network

off

Allow RFC1918/loopback/ULA/etc.

--max-sockets

128

Max concurrent sockets

--max-send-bytes

1048576

Max send payload

--max-recv-bytes

1048576

Max recv payload

--log-level

INFO

Logging level

Tools

Tool

Purpose

resolve_dns

Hostname → A/AAAA

tcp_connect

Connect TCP to IP:port

udp_open

Create UDP socket

tcp_send / udp_send

Send (utf8 or base64)

tcp_recv / udp_recv

Receive (base64 + optional text)

socket_poll

Check readability

list_sockets

Inspect open sockets

close_socket

Close (optional TCP RST)

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

Available Tools

10 tools
close_socketA

Close a socket and remove it from the registry. For TCP, reset=false performs a graceful FIN shutdown; reset=true attempts an abortive close (TCP RST). For UDP, reset is ignored.

Inputs: socket_id (required), reset. Returns: object

list_socketsA

List open sockets and their metadata (state, remote/local endpoints, idle time, byte/packet counters). Pass socket_id as a string, list of strings, or omit/null for all sockets.

Inputs: socket_id. Returns: result

resolve_dnsA

Resolve a hostname into IPv4 (A) and IPv6 (AAAA) addresses. Address ordering follows the OS resolver. Use this before tcp_connect/udp_send because those tools require IP literals, not hostnames.

Inputs: hostname (required). Returns: object

socket_pollA

Check whether a socket currently has readable data. If timeout_seconds > 0, wait until readable or timeout. Most clients can rely on timeout support in tcp_recv/udp_recv instead.

Inputs: socket_id (required), timeout_seconds. Returns: object

tcp_connectA

Create a TCP socket and connect to an IP:port. address must be an IPv4 or IPv6 literal (call resolve_dns first for hostnames). Returns socket_id for subsequent send/recv/close operations.

Inputs: port (required), address (required), timeout_seconds. Returns: object

tcp_recvA

Receive bytes from a TCP socket. timeout_seconds=0 (default) is non-blocking; >0 waits for at least one byte or timeout. Returns base64 (and text if valid UTF-8). bytes_received=0 with empty data indicates timeout or EOF (peer closed).

Inputs: socket_id (required), max_bytes, timeout_seconds. Returns: object

tcp_sendA

Send bytes over a connected TCP socket. encoding=utf8 encodes data as UTF-8; encoding=base64 base64-decodes data first.

Inputs: data (required), encoding (required), socket_id (required). Returns: object

udp_openA

Create an unbound outbound UDP socket. Use udp_send to send datagrams and udp_recv to receive them. Returns socket_id.

Inputs: no named parameters. Returns: object

udp_recvA

Receive one or more UDP datagrams (up to max_packets). timeout_seconds=0 (default) is non-blocking; >0 waits for at least one packet. Each packet includes source address/port, length, base64 data, and optional text.

Inputs: socket_id (required), max_packets, timeout_seconds. Returns: object

udp_sendC

Send a UDP datagram to address:port. address must be an IP literal. encoding=utf8 or base64 as with tcp_send.

Inputs: data (required), port (required), address (required), encoding (required), +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.9/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct operation (TCP connect/send/recv/close, UDP open/send/recv, DNS resolution, socket listing, polling). No overlap in functionality.

    Naming Consistency5/5

    All tools use consistent lowercase snake_case with a verb_noun pattern (e.g., tcp_connect, resolve_dns, close_socket). Adheres to a predictable naming convention.

    Tool Count5/5

    10 tools is appropriate for a socket utility server. It covers TCP and UDP client operations without being excessive or sparse.

    Completeness4/5

    Covers essential TCP/UDP client operations and DNS resolution. Missing server-side features (TCP listen, UDP bind) and advanced options, but the scope is clearly client-oriented.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • WireMCP

      0xKoda
      A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that provides LLMs with real-time network traffic analysis capabilities, enabling tasks like threat hunting, network diagnostics, and anomaly detection through Wireshark's tshark.
      7
      605
      MIT

    • Ruishu MCP

      xuange520
      F
      license
      A
      quality
      A
      maintenance
      An MCP server that bridges LLMs with dynamic real-world data by leveraging Chrome DevTools Protocol to intercept and reconstruct network traffic, enabling AI agents to extract high-quality structured data from complex web environments.
      3
      89
      -