Skip to main content
Glama
so2liu

PTY Debug MCP Server

by so2liu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

PTY Debug MCP Server

MCP server for debugging PTY/TTY/TUI programs. Enables Claude Code to spawn, interact with, and capture screen output from any terminal-based program.

Use Case: TUI Debugging

This MCP server allows Claude Code to control Claude Code itself, vim, top, and other TUI programs. This enables:

  • Automated TUI testing

  • Debugging terminal applications

  • Screen scraping from interactive programs

  • CI/CD integration for TUI apps

Demo: Claude Code controlling Claude Code

1. spawn_session({ command: "claude" })
2. send_input({ specialKey: "shift+tab" })  // cycle modes
3. send_input({ input: "what is 1+1?" })
4. send_input({ specialKey: "enter" })
5. get_snapshot()  // see Claude's response

Demo: Claude Code controlling vim

1. spawn_session({ command: "vim", args: ["test.txt"] })
2. send_input({ input: "i" })              // enter INSERT mode
3. send_input({ input: "Hello World!" })   // type text
4. send_input({ specialKey: "escape" })    // exit INSERT mode
5. send_input({ input: ":wq" })            // save command
6. send_input({ specialKey: "enter" })     // execute

Related MCP server: MCP TUI Test

Installation

Claude Code

claude mcp add pty-debug -- npx -y @so2liu/pty-mcp-server@latest

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pty-debug": {
      "command": "npx",
      "args": ["-y", "@so2liu/pty-mcp-server@latest"]
    }
  }
}

VS Code / Copilot

Add to VS Code settings or .vscode/mcp.json:

{
  "mcpServers": {
    "pty-debug": {
      "command": "npx",
      "args": ["-y", "@so2liu/pty-mcp-server@latest"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "pty-debug": {
      "command": "npx",
      "args": ["-y", "@so2liu/pty-mcp-server@latest"]
    }
  }
}

Cline

Add to Cline MCP settings:

{
  "mcpServers": {
    "pty-debug": {
      "command": "npx",
      "args": ["-y", "@so2liu/pty-mcp-server@latest"]
    }
  }
}

Gemini CLI

gemini mcp add pty-debug -- npx -y @so2liu/pty-mcp-server@latest

Codex CLI

codex mcp add pty-debug -- npx -y @so2liu/pty-mcp-server@latest

MCP Tools

Tool

Description

spawn_session

Start a TUI program in a PTY

send_input

Send text or special keys

get_snapshot

Capture current screen state

resize_terminal

Change terminal dimensions

list_sessions

List active sessions

close_session

Terminate a session

Special Keys

Supports all common shortcuts:

  • Basic: enter, tab, shift+tab, escape, backspace, delete

  • Arrows: up, down, left, right

  • With modifiers: shift+up, ctrl+right, alt+left, etc.

  • Control: ctrl+a to ctrl+z

  • Alt: alt+a to alt+z

  • Function: f1 to f12

  • Navigation: home, end, pageup, pagedown

Screen Snapshot Format

-------------------------------------------------------------------------------------
 1 |Processes: 643 total, 3 running, 640 sleeping                          17:57:23 |
 2 |Load Avg: 2.38, 2.75, 2.88  CPU usage: 13.13% user, 4.49% sys                    |
 3 |...                                                                              |
-------------------------------------------------------------------------------------

Development

# Install dependencies
bun install

# Development mode
bun run dev

# Build
bun run build

# Lint
bun run lint

Tech Stack

  • Node.js (runtime)

  • TypeScript

  • node-pty (PTY spawning)

  • @xterm/headless (terminal emulation)

  • @modelcontextprotocol/sdk (MCP server)

Publishing

Releases are automatically published to npm via GitHub Actions.

Setup (one-time)

  1. Create npm granular token at https://www.npmjs.com/settings/tokens/granular-access-tokens/new

    • Expiration: 90 days

    • Packages: @so2liu/pty-mcp-server

    • Permissions: Read and write

  2. Add NPM_TOKEN secret at https://github.com/so2liu/pty-mcp/settings/secrets/actions

  3. Set calendar reminder to rotate token every 90 days

Release new version

  1. Update version in package.json

  2. Create a GitHub release with tag (e.g., v1.0.1)

  3. GitHub Actions will automatically publish to npm

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • interactive-cli

    ohernandezdev
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to interact with interactive CLI processes via a real PTY, allowing them to send keystrokes, read screen output, and handle interactive prompts.
    4 npm
    1
    MIT

  • MCP TUI Test

    GeorgePearse
    A
    license
    Not graded
    quality
    F
    maintenance
    Enables AI assistants to test Terminal User Interface (TUI) applications by launching, interacting with, and verifying programmatic output and behavior.
    16
    MIT

  • spectatty

    dayvidwang
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to spawn and interact with real terminal sessions, capturing screenshots of rendered TUI output and sharing live sessions for debugging.
    2 npm
    1
    MIT

  • portal

    tiefeiyu
    A
    license
    A
    quality
    A
    maintenance
    Enables interaction with long-running interactive programs such as SSH, GDB, and REPLs. Provides tools to start, monitor, control, read/write I/O for these processes.
    13
    1
    MIT