TcpSocketMCP MCP Server for Raw TCP Sockets

Overview

TcpSocketMCP is a lightweight Model Context Protocol (MCP) server that exposes raw TCP socket access to AI models and external agents. It bridges MCP-capable models and arbitrary TCP endpoints so agents can open connections, send/receive byte streams, and automate interaction patterns (including buffering and trigger-driven events) without embedding socket logic into the model itself.

This server is useful when an agent must interact with legacy systems, network services (SMTP, IRC, Telnet-like interfaces), IoT devices, or custom TCP-based protocols. It provides concurrent connection handling, configurable response buffering, and automated triggers so models can be notified when specified patterns appear in the incoming stream.

Features

• Concurrent TCP connection handling (multiple client-server streams)
• Configurable response buffering and partial/complete message modes
• Automated trigger matching (notify MCP client on pattern matches)
• Simple JSON-based configuration and CLI startup
• Lightweight and extensible: add custom trigger handlers or access control
• Logs and runtime metrics for debugging interactions
• Designed to be used as an MCP “tool” by agent frameworks

Installation / Configuration

Clone and run the server (example Node.js workflow):

git clone https://github.com/SpaceyKasey/TcpSocketMCP.git
cd TcpSocketMCP
# install dependencies (example)
npm install
# start with default config
node server.js
# or specify a custom config file
node server.js --config ./config.json

Example config.json:

{
  "host": "0.0.0.0",
  "port": 5001,
  "maxConnections": 100,
  "bufferMode": "line",            // "line" | "byte" | "raw"
  "bufferSize": 8192,
  "triggerPatterns": [
    {"name": "login_prompt", "pattern": "Login:"},
    {"name": "error", "pattern": "ERROR"}
  ],
  "logLevel": "info"
}

Common CLI options (example)

• –config PATH : load configuration JSON
• –port NUM : override configured port
• –host ADDR : override host bind address
• –log-level LEVEL : set verbosity

Configuration options (table)

Available Resources

The server exposes the following MCP tool methods (example names):

• tcp.connect({host, port, id?}) → connectionId
• tcp.send({connectionId, data, encoding?}) → bytesSent
• tcp.read({connectionId, mode?, timeout?}) → bufferedData
• tcp.close({connectionId}) → closed
• tcp.list() → activeConnections
• tcp.subscribeTriggers({connectionId, triggers[]}) → subscriptionId

Example MCP invocation (JSON-RPC style payload):

{
  "tool": "tcp",
  "method": "connect",
  "params": {"host":"example.com","port":23}
}

When a configured trigger pattern matches, the server emits a trigger event to the MCP client with the connectionId, pattern name, and captured data.

Use Cases

• Interacting with telnet/console interfaces on network gear:
  • Agent opens TCP session, waits for login prompt, sends credentials, runs diagnostic commands, and collects output.
• Accessing legacy TCP-based APIs:
  • Models use raw byte streams for protocols without HTTP wrappers (e.g., custom message framing).
• Automating SMTP/POP/IMAP transactions in testing or integration environments:
  • Sequence commands and read responses using buffered reads and pattern triggers.
• Monitoring and alerting:
  • Watch for error patterns in a socket stream and trigger an agent workflow to remediate.
• Rapid prototyping and debugging:
  • Expose a TCP endpoint to an agent to simulate device interactions during development.

Example: Node.js TCP client to validate a connection

const net = require('net');

const client = net.createConnection({ host: '127.0.0.1', port: 5001 }, () => {
  console.log('connected');
  client.write('HELLO\n');
});

client.on('data', (data) => {
  console.log('received:', data.toString());
  // when done:
  client.end();
});

client.on('end', () => console.log('disconnected'));

Notes for Developers

• Start with small buffer sizes and line-mode for text protocols to avoid partial-line ambiguity.
• Use trigger patterns conservatively to avoid noisy events; prefer anchored or unique markers.
• Consider securing access via network policies or an ACL layer if exposing the server on public networks.
• The server is designed to be extended: add custom trigger handlers, authentication, or metrics exporters as needed.