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.

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

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