Skip to main content
Glama
PTY MCP Server
by almahdi

PTY MCP Server

pty-mcp is a Model Context Protocol (MCP) server designed to manage pseudo-terminal (PTY) sessions. Built with TypeScript and the Effect ecosystem, it provides a robust and type-safe interface for spawning, controlling, and interacting with terminal processes programmatically.

Features

  • Spawn Sessions: Create new PTY sessions with custom commands, arguments, and environment variables.

  • Interactive Control: Write data to stdin and read from stdout/stderr in real-time.

  • Session Management: List active sessions, monitor status, and terminate processes.

  • Effect Ecosystem: Leverages the power of the Effect library for error handling, concurrency, and resource management.

  • MCP Integration: Seamlessly exposes PTY capabilities to MCP-compliant clients.

Related MCP server: MCP (Model Context Protocol) Server

Installation

pnpm install

Usage

Build

pnpm run build

Start Server

pnpm start

Testing

pnpm run test

Author

Ali Almahdi Digital Innovation Architect & AI Enthusiast

Crafting the future of technology at the intersection of AI and human experience.

License

This project is licensed under the AGPL-3.0 License. See the LICENSE file for details.

Available Tools

5 tools
pty_killA
Destructive

Terminates a PTY session and optionally cleans up its buffer.

Behavior:

  • If the session is running, it will be killed (status becomes "killed")

  • If cleanup=false (default), the session remains in the list with its output buffer intact

  • If cleanup=true, the session is removed entirely and the buffer is freed

  • Keeping sessions without cleanup allows you to compare logs between runs

Use cleanup=false if you might want to read the output later. Use cleanup=true when you're done with the session entirely.

To send Ctrl+C instead of killing, use pty_write with data="\x03"

Inputs: id (required), cleanup.

pty_listA
Destructive

Lists all PTY sessions (active and exited).

Use this tool to:

  • See all running and exited PTY sessions

  • Get session IDs for use with other pty_* tools

  • Check the status and output line count of each session

  • Monitor which processes are still running

Sessions remain in the list after exit until explicitly cleaned up with pty_kill, allowing you to read their output logs.

Inputs: no named parameters.

pty_readA
Destructive

Reads output from a PTY session's buffer.

The PTY maintains a rolling buffer of output lines. Use offset and limit to paginate through the output.

Two modes:

  1. Standard mode (no pattern): Returns consecutive lines

  2. Search mode (with pattern): Filters lines by regex, returns matches with line numbers

The buffer stores up to PTY_MAX_BUFFER_LINES (default: 50000) lines. Older lines are discarded when the limit is reached.

Inputs: id (required), offset, limit, pattern, +1 more.

pty_spawnA
Destructive

Spawns a new PTY (pseudo-terminal) session that runs in the background.

Unlike synchronous bash commands, PTY sessions persist and allow you to:

  • Run long-running processes (dev servers, watch modes, etc.)

  • Send interactive input (including Ctrl+C, arrow keys, etc.)

  • Read output at any time

  • Manage multiple concurrent terminal sessions

Returns the session ID, which you can use with other pty_* tools.

Inputs: command (required), description (required), args, workdir, +3 more.

pty_writeA
Destructive

Sends input data to an active PTY session.

Use this tool to:

  • Type commands or text into an interactive terminal

  • Send special key sequences (Ctrl+C, Enter, arrow keys, etc.)

  • Respond to prompts in interactive programs

Common escape sequences:

  • Enter/newline: "\n" or "\r"

  • Ctrl+C (interrupt): "\x03"

  • Ctrl+D (EOF): "\x04"

  • Ctrl+Z (suspend): "\x1a"

  • Tab: "\t"

  • Arrow Up: "\x1b[A"

  • Arrow Down: "\x1b[B"

  • Arrow Right: "\x1b[C"

  • Arrow Left: "\x1b[D"

Inputs: id (required), data (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: pty_spawn creates sessions, pty_list enumerates them, pty_write sends input, pty_read retrieves output, and pty_kill terminates sessions. The descriptions reinforce these distinct roles, making tool selection unambiguous for an agent.

    Naming Consistency5/5

    All tools follow a consistent 'pty_' prefix with descriptive action suffixes (spawn, list, write, read, kill) in snake_case. This uniform pattern makes the tool set predictable and easy to navigate, with no deviations in naming conventions.

    Tool Count5/5

    With 5 tools, this server is well-scoped for managing pseudo-terminal sessions. Each tool serves a clear, necessary function (create, list, input, output, destroy), providing complete lifecycle coverage without bloat or redundancy, which is ideal for the domain.

    Completeness5/5

    The tool set offers complete CRUD/lifecycle coverage for PTY management: spawn (create), list (read), write (update input), read (retrieve output), and kill (delete). There are no obvious gaps; agents can fully manage sessions from creation to termination with all necessary interactions.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that enables AI assistants to interact with iTerm2 terminals, allowing creation and management of terminal sessions, command execution, and reading terminal output.
      5
      89 npm
      14
      ISC
    • -
      license
      Not graded
      quality
      D
      maintenance
      A TypeScript implementation of a Model Context Protocol server and client that enables interaction with language models (specifically Mistral running on Ollama).
      -
    • A
      license
      C
      quality
      D
      maintenance
      A Model Context Protocol server that enables clients to interact with a system terminal running in an Electron application, allowing for executing commands, managing terminal sessions, and retrieving output programmatically.
      5
      5
      MIT