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:

# 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 implementation
• node-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.

Returns:

{
  "session_id": "abc123def456...",
  "pid": 12345,
  "command": "/bin/bash",
  "cols": 120,
  "rows": 30
}

pty_write

Send input to a PTY session. Supports escape sequences.

Escape Sequences:

Returns:

{ "written": 5 }

pty_read

Read buffered output from a PTY session.

Returns:

{
  "output": "user@host:~$ ",
  "exited": false,
  "exit_code": null,
  "signal": null
}

pty_resize

Resize a PTY terminal for full-screen applications.

pty_kill

Terminate a PTY session and clean up resources.

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

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

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:

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