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 --versionto check) - npm (comes with Node.js)
- Build tools for native modules
To check/install prerequisites:
# 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
# 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
npm install
This installs:
@modelcontextprotocol/sdk- The MCP SDK for server implementationnode-pty- Native PTY bindings (requires build tools)
Troubleshooting node-pty build failures:
# 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:
# 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:
claude mcp add -s user pty-mcp -- node /full/path/to/pty-mcp/server.js
Step 4: Verify Installation
# 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:
{
"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:
{ "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:
{
"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
# 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
# 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
- Ensure you're using the correct
session_idfrompty_spawn - Check if session exited:
pty_listor checkexitedfield inpty_read - 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:
### 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