Ryan Malloy
5595f1aef1
- Server mode documentation - Terminal escape sequences (send_key) - ANSI stripping, regex, keepalive - Connection stats and transcripts - Security section
131 lines
3.0 KiB
Markdown
131 lines
3.0 KiB
Markdown
# mctelnet
|
|
|
|
**Telnet for LLMs.** Connect to BBSes, MUDs, network devices, or host your own telnet services.
|
|
|
|
```bash
|
|
claude mcp add mctelnet "uvx mctelnet"
|
|
```
|
|
|
|
## Why?
|
|
|
|
LLMs can now interact with the vast world of telnet-accessible systems:
|
|
- **Retro computing** - BBSes, ASCII art servers, text adventures
|
|
- **Network ops** - Routers, switches, legacy infrastructure
|
|
- **Automation** - Expect-style scripting for any interactive prompt
|
|
- **Hosting** - Run telnet services that LLMs can manage
|
|
|
|
## Quick Start
|
|
|
|
```python
|
|
# Watch Star Wars in ASCII (really!)
|
|
connect("towel.blinkenlights.nl", 23, strip_ansi=True)
|
|
|
|
# Login to a server
|
|
expect_send(conn_id, "login:", "admin")
|
|
expect_send(conn_id, "Password:", "secret", hide_send=True)
|
|
expect_send(conn_id, "$ ", "uptime")
|
|
```
|
|
|
|
## Features
|
|
|
|
### Client Mode - Connect Anywhere
|
|
|
|
| Tool | What it does |
|
|
|------|-------------|
|
|
| `connect` | Connect with optional ANSI stripping, keepalive |
|
|
| `send` | Send text, auto-read response |
|
|
| `send_key` | Send escape sequences (ctrl-c, arrows, F-keys) |
|
|
| `expect` | Wait for patterns (supports regex) |
|
|
| `expect_send` | Wait then send - perfect for prompts |
|
|
| `run_script` | Full automation sequences |
|
|
| `connection_info` | Stats: bytes sent/received, uptime |
|
|
| `get_transcript` | Complete session history |
|
|
|
|
### Server Mode - Host Services
|
|
|
|
| Tool | What it does |
|
|
|------|-------------|
|
|
| `start_server` | Listen on a port (localhost by default) |
|
|
| `list_clients` | See who's connected |
|
|
| `send_client` | Send to specific client |
|
|
| `broadcast` | Send to all clients |
|
|
| `read_client` | Get buffered client input |
|
|
|
|
## Examples
|
|
|
|
### Expect-Style Automation
|
|
|
|
```python
|
|
# Scripted login + commands
|
|
run_script(conn_id, [
|
|
{"expect": "login:", "send": "admin"},
|
|
{"expect": "Password:", "send": "secret", "hide": True},
|
|
{"expect": "$ ", "send": "show version"},
|
|
{"expect": "$ ", "send": "exit"}
|
|
])
|
|
```
|
|
|
|
### Terminal Keys
|
|
|
|
```python
|
|
# Send escape sequences
|
|
send_key(conn_id, "ctrl-c") # Interrupt
|
|
send_key(conn_id, "up") # Arrow key
|
|
send_key(conn_id, "f1") # Function key
|
|
send_key(conn_id, "break") # Telnet break
|
|
|
|
# See all available keys
|
|
list_keys()
|
|
```
|
|
|
|
### Regex Pattern Matching
|
|
|
|
```python
|
|
# Flexible matching
|
|
expect(conn_id, [r"user(name)?:", r"login:"], regex=True)
|
|
expect_send(conn_id, "password", "secret", ignore_case=True)
|
|
```
|
|
|
|
### Host a Service
|
|
|
|
```python
|
|
# Start server (binds localhost:2323)
|
|
start_server(2323)
|
|
|
|
# Send welcome to new connections
|
|
send_client(server_id, client_id, "Welcome to my LLM-powered service!")
|
|
|
|
# Broadcast to everyone
|
|
broadcast(server_id, "Server shutting down in 5 minutes")
|
|
```
|
|
|
|
## Installation
|
|
|
|
**With Claude Code:**
|
|
```bash
|
|
claude mcp add mctelnet "uvx mctelnet"
|
|
```
|
|
|
|
**Standalone:**
|
|
```bash
|
|
uvx mctelnet
|
|
```
|
|
|
|
**From source:**
|
|
```bash
|
|
git clone https://git.supported.systems/MCP/mctelnet
|
|
cd mctelnet
|
|
uv run mctelnet
|
|
```
|
|
|
|
## Security
|
|
|
|
- Server mode binds to `127.0.0.1` by default (localhost only)
|
|
- Port validation (1-65535)
|
|
- Connection limits prevent resource exhaustion
|
|
- Graceful shutdown cleans up all connections
|
|
|
|
## License
|
|
|
|
MIT
|