# mctelnet

[![PyPI](https://img.shields.io/pypi/v/mctelnet)](https://pypi.org/project/mctelnet/)
[![Python](https://img.shields.io/pypi/pyversions/mctelnet)](https://pypi.org/project/mctelnet/)
[![License](https://img.shields.io/pypi/l/mctelnet)](https://github.com/MCP/mctelnet/blob/main/LICENSE)

**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