A Model Context Protocol (MCP) server that provides raw TCP socket access, enabling AI models to interact directly with network services using raw TCP Sockets. Supports multiple concurrent connections, buffering of response data and triggering automatic responses.

Many network services and IoT devices communicate via raw TCP protocols that aren't covered by existing HTTP-based MCP servers. TcpSocketMCP enables:

• Direct interaction with embedded devices and IoT systems
• Network protocol debugging and testing
• Legacy system integration without HTTP wrappers
• Protocol reverse engineering and analysis
• Automated responses via trigger patterns (useful for IRC, telnet, custom protocols)

This addresses the need for low-level network access that several community members have expressed, particularly for industrial automation, IoT development, and network security testing scenarios.

Interrogating a device to figure out what it is

Sending data to the device

Sample output from TCP interactions

# Install with pip
pip install TcpSocketMCP

# Install with uv (recommended)
uv add TcpSocketMCP

# Add to Claude Code (recommended)
claude mcp add rawtcp -- uvx TcpSocketMCP

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "tcp-socket": {
      "command": "TcpSocketMCP",
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "tcp-socket": {
      "command": "python",
      "args": ["/path/to/tcp-socket-mcp/run.py"],
      "env": {}
    }
  }
}

# Clone the repository
git clone https://github.com/kaseyk/tcp-socket-mcp.git
cd tcp-socket-mcp

# Install with uv (recommended)
uv pip install -e .

# Or install with pip
pip install -e .

# Run the server directly
python run.py

# Or use the command
TcpSocketMCP

Once configured via MCP, the following tools become available to the AI model:

Opens a TCP connection to any host:port

• Returns a connection_id for subsequent operations
• Supports custom connection_id for pre-registered triggers
• Example: tcp_connect("example.com", 80)

Sends data over an established connection

• Encoding options: utf-8, hex (recommended for binary), base64
• Hex format: Plain pairs like "48656C6C6F" for "Hello"
• Terminator: Optional hex suffix like "0D0A" for CRLF

Reads received data from connection buffer

• Data may not be immediately available after sending
• Buffer stores all received data until cleared
• Supports index/count for partial reads
• Format options: utf-8, hex, base64

Closes connection and frees resources

• Always close connections when done
• All triggers automatically removed

Sets automatic responses for pattern matches

• Pre-registration: Set triggers before connecting for immediate activation
• Supports regex patterns with capture groups ($1, $2)
• Response fires automatically when pattern matches
• Perfect for protocol handshakes (IRC PING/PONG, etc.)

Combines connect + send in one atomic operation

• Essential for time-sensitive protocols
• Useful for immediate handshakes or banner grabbing
• Returns connection_id for further operations

• tcp_list_connections: View all active connections with statistics
• tcp_connection_info: Get detailed info about specific connection
• tcp_buffer_info: Check buffer statistics without reading data
• tcp_clear_buffer: Clear received data from buffer
• tcp_remove_trigger: Remove specific auto-response trigger

# Connect to a service
conn_id = tcp_connect("example.com", 80)

# Send data (hex encoding recommended for protocols)
tcp_send(conn_id, "474554202F20485454502F312E310D0A", encoding="hex")  # GET / HTTP/1.1\r\n

# Read response (may need to wait for data)
response = tcp_read_buffer(conn_id)

# Clean up
tcp_disconnect(conn_id)

# Pre-register trigger for IRC PING/PONG
tcp_set_trigger("irc-conn", "ping-handler", "^PING :(.+)", "PONG :$1\r\n")

# Connect with pre-registered triggers
tcp_connect("irc.server.com", 6667, connection_id="irc-conn")
# PING responses now happen automatically!

# Use hex encoding for precise byte control
tcp_send(conn_id, "0001000400000001", encoding="hex")  # Binary protocol header

# Read response in hex for analysis
response = tcp_read_buffer(conn_id, format="hex")

Many text protocols (HTTP, SMTP, IRC) require specific line endings. Use hex encoding to avoid JSON escaping issues:

# Common hex sequences:
# 0D0A     = \r\n (CRLF) - HTTP, SMTP, IRC
# 0A       = \n (LF) - Unix line ending
# 0D0A0D0A = \r\n\r\n - HTTP header terminator
# 00       = Null byte - Binary protocols

• Network responses aren't instant - use tcp_buffer_info to check for data
• Consider implementing retry logic with small delays
• Buffer accumulates all received data - clear when needed

TcpSocketMCP maintains enterprise-grade quality through comprehensive testing:

• 85% Coverage (exceeds 80% target)
• 80+ Comprehensive Tests across all components
• Cross-Platform Testing (Ubuntu, Windows, macOS)
• Python 3.10-3.12 Support

• Automated CI/CD with GitHub Actions
• Security Scanning with Bandit and Safety
• Code Quality Analysis with Ruff and MyPy
• Performance Monitoring and complexity analysis

# Install with test dependencies
uv pip install -e .
uv pip install pytest pytest-asyncio pytest-cov

# Run full test suite with coverage
uv run pytest tests/ --cov=src/TcpSocketMCP --cov-report=term-missing

# Quick test run
uv run pytest

See TESTING.md for comprehensive testing documentation.

MIT