Skip to main content
Glama
so2liu

PTY Debug MCP Server

by so2liu
OverviewSchemaRelated ServersScoreDiscussions
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: PTY MCP Server

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 installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
0dRelease cycle
11Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

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/so2liu/pty-mcp'

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