Skip to main content
Glama
Sign In
PTY Debug MCP Server

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • portal

      tiefeiyu
      F
      license
      A
      quality
      B
      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
      -