PTY MCP Server

How to use

You interact with the PTY MCP Server through an MCP client by creating and controlling virtual terminal sessions. Start a shell or an interactive program, then send input and read output as if you were using a real terminal. You can also resize the terminal to support full-screen programs and clean up sessions when you are done.

How to install

Prerequisites you need to check first are Node.js version 18 or newer and npm, along with build tools for native modules.

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

How to install

Next, clone the MCP server repository and install dependencies so you can run the PTY MCP Server locally.

# 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

# Install dependencies
npm install

How to install

Register the server with Claude Code so you can use it within your projects. You must run the CLI command to add the MCP server to your user configuration.

# 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

How to install

After registering, verify that Claude Code recognizes the MCP server and is ready for use.

# List registered MCP servers
claude mcp list

# Should show pty-mcp with status

Notes on testing the server

Once Claude Code restarts, you can test the server by creating a shell session, reading the prompt, sending a command, and then cleaning up the session.

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

Configuration

Key settings for the PTY MCP Server are listed below to help you plan resource usage and behavior.

{
  "Max sessions": 10,
  "Session timeout": "30 minutes",
  "Buffer size": "1 MB",
  "Input size": "1 MB",
  "Default terminal": "120x30",
  "Max terminal": "500x200"
}

Troubleshooting

If you encounter issues, use the following guidance to resolve common problems quickly.

### Server not found after 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
```

```bash
### node-pty build fails
sudo apt-get install -y python3 make g++
rm -rf node_modules package-lock.json
npm install
```

```bash
### 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)
```

```bash
### Output contains escape codes
Terminal output includes ANSI escape sequences for colors and formatting. This is normal behavior for terminal applications.

Security

Security considerations for the PTY MCP Server focus on controlled command execution, input handling, and session lifecycle to minimize risk.

- 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

A concise integration guide helps Claude Code understand how to work with the PTY MCP Server within your projects.

### 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, htop, 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
`

Notes

This server is designed to provide robust PTY sessions while maintaining safe defaults and resource limits to prevent abuse.

pty_spawn

Create a new interactive PTY session and return a session_id for subsequent operations.

pty_write

Send input to a PTY session, including control and escape sequences to drive interactive programs.

pty_read

Read buffered output from a PTY session, with optional timeout and buffer control.

pty_resize

Resize the PTY terminal to support full-screen applications and dynamic layouts.

pty_kill

Terminate a PTY session and free associated resources.

pty_list

List all currently active PTY sessions.