Skip to main content
Glama
dblmca

PTY MCP Server

by dblmca
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

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

# 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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dblmca/pty-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server