# PTY MCP Server
An MCP (Model Context Protocol) server that provides interactive PTY (pseudo-terminal) sessions for AI assistants like Claude Code. This enables interaction with programs that require full terminal emulation such as vim, ssh, less, top, interactive REPLs, and more.
## LLM Deployment Instructions
This section provides complete step-by-step instructions for an LLM to deploy this MCP server autonomously.
### Prerequisites
Before starting, ensure the system has:
- Node.js >= 18.0.0 (`node --version` to check)
- npm (comes with Node.js)
- Build tools for native modules
To check/install prerequisites:
```bash
# Check Node.js version
node --version # Should be >= 18.0.0
# If Node.js is missing or outdated, install via nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
# Install build tools (required for node-pty native module)
# Ubuntu/Debian:
sudo apt-get update && sudo apt-get install -y python3 make g++
# macOS:
xcode-select --install
# Fedora/RHEL:
sudo dnf install -y python3 make gcc-c++
```
### Step 1: Clone the Repository
```bash
# Create MCP servers directory if it doesn't exist
mkdir -p ~/mcp-servers
cd ~/mcp-servers
# Clone the repository
git clone https://github.com/dblmca/pty-mcp.git
cd pty-mcp
```
### Step 2: Install Dependencies
```bash
npm install
```
This installs:
- `@modelcontextprotocol/sdk` - The MCP SDK for server implementation
- `node-pty` - Native PTY bindings (requires build tools)
**Troubleshooting `node-pty` build failures:**
```bash
# If npm install fails with node-pty errors, install build dependencies first
sudo apt-get install -y python3 make g++ # Ubuntu/Debian
# Then retry
npm install
```
### Step 3: Register with Claude Code
**CRITICAL**: Claude Code does NOT use `~/.claude/.mcp.json` directly. You MUST use the CLI:
```bash
# Add to user config (available in all projects)
claude mcp add -s user pty-mcp -- node ~/mcp-servers/pty-mcp/server.js
```
If using a different installation path, adjust accordingly:
```bash
claude mcp add -s user pty-mcp -- node /full/path/to/pty-mcp/server.js
```
### Step 4: Verify Installation
```bash
# List registered MCP servers
claude mcp list
# Should show pty-mcp with status
```
### Step 5: Test the Server
After restarting Claude Code, test with:
```
1. Call pty_spawn with no arguments to create a shell session
2. Call pty_read to see the shell prompt
3. Call pty_write with input: "echo hello\r"
4. Call pty_read to see the output
5. Call pty_kill to clean up
```
---
## Tools Reference
### `pty_spawn`
Create a new interactive PTY session.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `command` | string | No | User's shell | Command to run |
| `args` | string[] | No | [] | Command arguments |
| `cwd` | string | No | Current dir | Working directory |
| `cols` | number | No | 120 | Terminal columns (max: 500) |
| `rows` | number | No | 30 | Terminal rows (max: 200) |
| `env` | object | No | {} | Additional environment variables |
**Returns:**
```json
{
"session_id": "abc123def456...",
"pid": 12345,
"command": "/bin/bash",
"cols": 120,
"rows": 30
}
```
### `pty_write`
Send input to a PTY session. Supports escape sequences.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Session ID from `pty_spawn` |
| `input` | string | Yes | Input to send |
**Escape Sequences:**
| Sequence | Key | Use Case |
|----------|-----|----------|
| `\r` | Enter | Execute commands |
| `\n` | Newline | Multi-line input |
| `\t` | Tab | Autocomplete |
| `\x03` | Ctrl-C | Interrupt/cancel |
| `\x04` | Ctrl-D | EOF/exit |
| `\x1b` | Escape | Exit modes (vim, less) |
| `\x1b[A` | Arrow Up | History/navigation |
| `\x1b[B` | Arrow Down | History/navigation |
| `\x1b[C` | Arrow Right | Cursor movement |
| `\x1b[D` | Arrow Left | Cursor movement |
**Returns:**
```json
{ "written": 5 }
```
### `pty_read`
Read buffered output from a PTY session.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `session_id` | string | Yes | - | Session ID |
| `timeout_ms` | number | No | 100 | Wait time for output (max: 5000) |
| `clear_buffer` | boolean | No | true | Clear buffer after reading |
**Returns:**
```json
{
"output": "user@host:~$ ",
"exited": false,
"exit_code": null,
"signal": null
}
```
### `pty_resize`
Resize a PTY terminal for full-screen applications.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Session ID |
| `cols` | number | Yes | New columns (max: 500) |
| `rows` | number | Yes | New rows (max: 200) |
### `pty_kill`
Terminate a PTY session and clean up resources.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `session_id` | string | Yes | - | Session ID |
| `signal` | string | No | SIGHUP | Signal: SIGHUP, SIGTERM, SIGKILL, SIGINT |
### `pty_list`
List all active PTY sessions. No parameters required.
---
## Usage Examples
### SSH Session
```
1. pty_spawn { command: "ssh", args: ["user@192.168.1.100"] }
2. pty_read { session_id: "...", timeout_ms: 5000 } # Wait for prompt/password
3. pty_write { session_id: "...", input: "password\r" } # If password needed
4. pty_read { session_id: "..." } # Get remote prompt
5. pty_write { session_id: "...", input: "hostname\r" } # Run commands
6. pty_read { session_id: "..." }
7. pty_write { session_id: "...", input: "exit\r" } # Disconnect
8. pty_kill { session_id: "..." } # Cleanup
```
### Python REPL
```
1. pty_spawn { command: "python3" }
2. pty_read { session_id: "..." } # ">>> "
3. pty_write { session_id: "...", input: "import math\r" }
4. pty_write { session_id: "...", input: "print(math.pi)\r" }
5. pty_read { session_id: "..." } # "3.141592653589793\n>>> "
6. pty_write { session_id: "...", input: "\x04" } # Ctrl-D to exit
```
### Vim Editing
```
1. pty_spawn { command: "vim", args: ["file.txt"] }
2. pty_read { session_id: "...", timeout_ms: 1000 } # Wait for vim
3. pty_write { session_id: "...", input: "i" } # Insert mode
4. pty_write { session_id: "...", input: "Hello, World!" }
5. pty_write { session_id: "...", input: "\x1b" } # Escape
6. pty_write { session_id: "...", input: ":wq\r" } # Save and quit
7. pty_kill { session_id: "..." }
```
### Interactive Program (top, htop)
```
1. pty_spawn { command: "top" }
2. pty_read { session_id: "...", timeout_ms: 2000 } # Get display
3. pty_write { session_id: "...", input: "q" } # Quit top
# Or: pty_write { session_id: "...", input: "\x03" } # Ctrl-C
```
---
## Configuration
| Setting | Value | Description |
|---------|-------|-------------|
| Max sessions | 10 | Maximum concurrent PTY sessions |
| Session timeout | 30 minutes | Idle sessions auto-cleanup |
| Buffer size | 1 MB | Max output buffer per session |
| Input size | 1 MB | Max input per write |
| Default terminal | 120x30 | Default cols x rows |
| Max terminal | 500x200 | Maximum cols x rows |
---
## Troubleshooting
### Server not found after registration
```bash
# Verify registration
claude mcp list
# If missing, re-add
claude mcp add -s user pty-mcp -- node ~/mcp-servers/pty-mcp/server.js
# Restart Claude Code
```
### node-pty build fails
```bash
# Install build dependencies
sudo apt-get install -y python3 make g++
# Clear npm cache and retry
rm -rf node_modules package-lock.json
npm install
```
### Session commands not working
1. Ensure you're using the correct `session_id` from `pty_spawn`
2. Check if session exited: `pty_list` or check `exited` field in `pty_read`
3. For password prompts, use longer `timeout_ms` (e.g., 5000)
### Output contains escape codes
Terminal output includes ANSI escape sequences for colors and formatting. This is normal behavior for terminal applications.
---
## Security
- Commands restricted to standard system paths
- Shell metacharacters rejected in command names
- Environment variable names validated
- Input/buffer sizes limited
- Sessions auto-expire after 30 minutes
---
## Claude Code Integration (CLAUDE.md snippet)
Add this to your project's `CLAUDE.md` file to help Claude Code understand how to use this MCP server:
```markdown
### PTY MCP Server (Interactive Terminal)
The `pty-mcp` server provides interactive terminal (PTY) sessions for programs that require full terminal emulation (vim, ssh, less, top, interactive REPLs, etc.).
**Location:** `~/mcp-servers/pty-mcp/`
**When to Use:**
- Interactive programs that need terminal emulation (vim, nano, less, top, htop)
- SSH sessions
- Interactive REPLs (python, node, irb)
- Programs that require Ctrl-C, Ctrl-D, or arrow keys
- Any program that doesn't work well with the standard Bash tool
**MCP Tools:**
- `pty_spawn` - Create a new PTY session (returns session_id)
- `pty_write` - Send input to a session (supports escape sequences)
- `pty_read` - Read buffered output from a session
- `pty_resize` - Resize terminal dimensions
- `pty_kill` - Kill a session
- `pty_list` - List all active sessions
**Escape Sequences for `pty_write`:**
| Sequence | Meaning |
|----------|---------|
| `\r` | Enter/Return |
| `\x03` | Ctrl-C (interrupt) |
| `\x04` | Ctrl-D (EOF) |
| `\x1b` | Escape |
| `\x1b[A` | Arrow Up |
| `\x1b[B` | Arrow Down |
| `\x1b[C` | Arrow Right |
| `\x1b[D` | Arrow Left |
**Usage Examples:**
\`\`\`
# Basic shell session
1. pty_spawn {} → { session_id: "abc123" }
2. pty_read { session_id: "abc123" } → { output: "$ " }
3. pty_write { session_id: "abc123", input: "ls -la\r" }
4. pty_read { session_id: "abc123" } → { output: "..." }
5. pty_kill { session_id: "abc123" }
# Python REPL
1. pty_spawn { command: "python3" }
2. pty_write { session_id: "...", input: "x = 42\r" }
3. pty_write { session_id: "...", input: "print(x * 2)\r" }
4. pty_read { session_id: "..." } → { output: "84\n>>> " }
5. pty_write { session_id: "...", input: "\x04" } # Ctrl-D to exit
# Vim editing
1. pty_spawn { command: "vim", args: ["file.txt"] }
2. pty_write { session_id: "...", input: "i" } # Insert mode
3. pty_write { session_id: "...", input: "Hello!" }
4. pty_write { session_id: "...", input: "\x1b" } # Escape
5. pty_write { session_id: "...", input: ":wq\r" } # Save and quit
\`\`\`
**Configuration:**
- Max 10 concurrent sessions
- 30-minute idle timeout (auto-cleanup)
- 1MB output buffer per session
- Default terminal: 120x30
```
---
## License
MIT
