# TCP Socket MCP Server
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.
## Demo
*Interrogating a device to figure out what it is*
*Sending data to the device*
*Sample output from TCP interactions*
## Installation & Setup
### Install from PyPI
```bash
# Install with pip
pip install TcpSocketMCP
# Install with uv (recommended)
uv add TcpSocketMCP
# Add to Claude Code (recommended)
claude mcp add rawtcp -- uvx TcpSocketMCP
```
### For Claude Desktop
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`
#### Option 1: Using installed package (recommended)
```json
{
"mcpServers": {
"tcp-socket": {
"command": "TcpSocketMCP",
"env": {}
}
}
}
```
#### Option 2: From source
```json
{
"mcpServers": {
"tcp-socket": {
"command": "python",
"args": ["/path/to/tcp-socket-mcp/run.py"],
"env": {}
}
}
}
```
### Development Setup
```bash
# 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
```
## Available Tools
Once configured via MCP, the following tools become available to the AI model:
### Core Connection Tools
#### tcp_connect
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)`
#### tcp_send
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
#### tcp_read_buffer
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`
#### tcp_disconnect
Closes connection and frees resources
- Always close connections when done
- All triggers automatically removed
### Advanced Features
#### tcp_set_trigger
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.)
#### tcp_connect_and_send
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
### Utility Tools
- **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
## Usage Examples
### Basic TCP Communication
```python
# 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)
```
### Automated Protocol Handling
```python
# 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!
```
### Working with Binary Protocols
```python
# 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")
```
## Important Notes
### Hex Encoding for Line Endings
Many text protocols (HTTP, SMTP, IRC) require specific line endings. Use hex encoding to avoid JSON escaping issues:
```python
# 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
```
### Timing Considerations
- 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
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "TcpSocketMCP",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Kassandra Karan <kaseykaran@icloud.com>",
"keywords": "mcp, model-context-protocol, network, protocol, raw-socket, socket, tcp",
"author": null,
"author_email": "Kassandra Karan <kaseykaran@icloud.com>",
"download_url": "https://files.pythonhosted.org/packages/f3/df/36c28026ee1a4a2685d40531ea01203f55958de3a51095ef27e18ecf328b/tcpsocketmcp-0.1.3.tar.gz",
"platform": null,
"description": "# TCP Socket MCP Server\n\nA Model Context Protocol (MCP) server that provides raw TCP socket access, enabling AI models to interact directly with network services using raw TCP Sockets.\nSupports multiple concurrent connections, buffering of response data and triggering automatic responses.\n\n## Demo\n\n\n*Interrogating a device to figure out what it is*\n\n\n*Sending data to the device*\n\n\n*Sample output from TCP interactions*\n\n## Installation & Setup\n\n### Install from PyPI\n\n```bash\n# Install with pip\npip install TcpSocketMCP\n\n# Install with uv (recommended)\nuv add TcpSocketMCP\n\n# Add to Claude Code (recommended)\nclaude mcp add rawtcp -- uvx TcpSocketMCP\n```\n\n### For Claude Desktop\n\nAdd the server to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n#### Option 1: Using installed package (recommended)\n```json\n{\n \"mcpServers\": {\n \"tcp-socket\": {\n \"command\": \"TcpSocketMCP\",\n \"env\": {}\n }\n }\n}\n```\n\n#### Option 2: From source\n```json\n{\n \"mcpServers\": {\n \"tcp-socket\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/tcp-socket-mcp/run.py\"],\n \"env\": {}\n }\n }\n}\n```\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/kaseyk/tcp-socket-mcp.git\ncd tcp-socket-mcp\n\n# Install with uv (recommended)\nuv pip install -e .\n\n# Or install with pip\npip install -e .\n\n# Run the server directly\npython run.py\n\n# Or use the command\nTcpSocketMCP\n```\n\n## Available Tools\n\nOnce configured via MCP, the following tools become available to the AI model:\n\n### Core Connection Tools\n\n#### tcp_connect\nOpens a TCP connection to any host:port\n- Returns a `connection_id` for subsequent operations\n- Supports custom connection_id for pre-registered triggers\n- Example: `tcp_connect(\"example.com\", 80)`\n\n#### tcp_send \nSends data over an established connection\n- **Encoding options**: `utf-8`, `hex` (recommended for binary), `base64`\n- **Hex format**: Plain pairs like `\"48656C6C6F\"` for \"Hello\"\n- **Terminator**: Optional hex suffix like `\"0D0A\"` for CRLF\n\n#### tcp_read_buffer\nReads received data from connection buffer\n- Data may not be immediately available after sending\n- Buffer stores all received data until cleared\n- Supports `index`/`count` for partial reads\n- Format options: `utf-8`, `hex`, `base64`\n\n#### tcp_disconnect\nCloses connection and frees resources\n- Always close connections when done\n- All triggers automatically removed\n\n### Advanced Features\n\n#### tcp_set_trigger\nSets automatic responses for pattern matches\n- **Pre-registration**: Set triggers before connecting for immediate activation\n- Supports regex patterns with capture groups (`$1`, `$2`)\n- Response fires automatically when pattern matches\n- Perfect for protocol handshakes (IRC PING/PONG, etc.)\n\n#### tcp_connect_and_send\nCombines connect + send in one atomic operation\n- Essential for time-sensitive protocols\n- Useful for immediate handshakes or banner grabbing\n- Returns connection_id for further operations\n\n### Utility Tools\n\n- **tcp_list_connections**: View all active connections with statistics\n- **tcp_connection_info**: Get detailed info about specific connection\n- **tcp_buffer_info**: Check buffer statistics without reading data\n- **tcp_clear_buffer**: Clear received data from buffer\n- **tcp_remove_trigger**: Remove specific auto-response trigger\n\n## Usage Examples\n\n### Basic TCP Communication\n\n```python\n# Connect to a service\nconn_id = tcp_connect(\"example.com\", 80)\n\n# Send data (hex encoding recommended for protocols)\ntcp_send(conn_id, \"474554202F20485454502F312E310D0A\", encoding=\"hex\") # GET / HTTP/1.1\\r\\n\n\n# Read response (may need to wait for data)\nresponse = tcp_read_buffer(conn_id)\n\n# Clean up\ntcp_disconnect(conn_id)\n```\n\n### Automated Protocol Handling\n\n```python\n# Pre-register trigger for IRC PING/PONG\ntcp_set_trigger(\"irc-conn\", \"ping-handler\", \"^PING :(.+)\", \"PONG :$1\\r\\n\")\n\n# Connect with pre-registered triggers\ntcp_connect(\"irc.server.com\", 6667, connection_id=\"irc-conn\")\n# PING responses now happen automatically!\n```\n\n### Working with Binary Protocols\n\n```python\n# Use hex encoding for precise byte control\ntcp_send(conn_id, \"0001000400000001\", encoding=\"hex\") # Binary protocol header\n\n# Read response in hex for analysis\nresponse = tcp_read_buffer(conn_id, format=\"hex\")\n```\n\n## Important Notes\n\n### Hex Encoding for Line Endings\n\nMany text protocols (HTTP, SMTP, IRC) require specific line endings. Use hex encoding to avoid JSON escaping issues:\n\n```python\n# Common hex sequences:\n# 0D0A = \\r\\n (CRLF) - HTTP, SMTP, IRC\n# 0A = \\n (LF) - Unix line ending\n# 0D0A0D0A = \\r\\n\\r\\n - HTTP header terminator\n# 00 = Null byte - Binary protocols\n```\n\n### Timing Considerations\n\n- Network responses aren't instant - use `tcp_buffer_info` to check for data\n- Consider implementing retry logic with small delays\n- Buffer accumulates all received data - clear when needed\n\n## License\n\nMIT",
"bugtrack_url": null,
"license": null,
"summary": "MCP server for raw TCP socket access with buffer management and triggers",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/SpaceyKasey/TcpSocketMCP/",
"Issues": "https://github.com/SpaceyKasey/TcpSocketMCP/issues",
"Repository": "https://github.com/SpaceyKasey/TcpSocketMCP/"
},
"split_keywords": [
"mcp",
" model-context-protocol",
" network",
" protocol",
" raw-socket",
" socket",
" tcp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f70237a81e4a549f2e5a193a5cb5ad47091f66f329c85904e80e638f166989ff",
"md5": "a8802059c87a7eda3b178c1a8253e891",
"sha256": "9153d83fcbcb92b9922360fb16c7345731ab3e6f9c1c6ff137f2d680e4377431"
},
"downloads": -1,
"filename": "tcpsocketmcp-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a8802059c87a7eda3b178c1a8253e891",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 13896,
"upload_time": "2025-08-16T14:58:06",
"upload_time_iso_8601": "2025-08-16T14:58:06.134191Z",
"url": "https://files.pythonhosted.org/packages/f7/02/37a81e4a549f2e5a193a5cb5ad47091f66f329c85904e80e638f166989ff/tcpsocketmcp-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f3df36c28026ee1a4a2685d40531ea01203f55958de3a51095ef27e18ecf328b",
"md5": "fcf3abe5241d436d241aadf2391e72f1",
"sha256": "dc044cf2496c9a5f4d17d82b19d72a390c1bf778c287419c4466f012c9ab2207"
},
"downloads": -1,
"filename": "tcpsocketmcp-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "fcf3abe5241d436d241aadf2391e72f1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 6125768,
"upload_time": "2025-08-16T14:58:08",
"upload_time_iso_8601": "2025-08-16T14:58:08.257271Z",
"url": "https://files.pythonhosted.org/packages/f3/df/36c28026ee1a4a2685d40531ea01203f55958de3a51095ef27e18ecf328b/tcpsocketmcp-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-16 14:58:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SpaceyKasey",
"github_project": "TcpSocketMCP",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tcpsocketmcp"
}
JSON
