PTY MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@PTY MCP Server Spawn a new terminal and run 'npm install'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 installUsage
Build
pnpm run buildStart Server
pnpm startTesting
pnpm run testAuthor
Ali Almahdi Digital Innovation Architect & AI Enthusiast
Crafting the future of technology at the intersection of AI and human experience.
Website: ali.ac
GitHub: @almahdi
X (Twitter): @alialmahdi
License
This project is licensed under the AGPL-3.0 License. See the LICENSE file for details.
Available Tools
5 toolspty_killADestructive
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_listADestructive
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_readADestructive
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:
Standard mode (no pattern): Returns consecutive lines
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_spawnADestructive
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_writeADestructive
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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A TypeScript MCP server for Home Assistant, enabling programmatic management of entities, automati…
A Model Context Protocol server for Wix AI tools
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Related MCP Servers
- AlicenseAqualityDmaintenanceA 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.589 npm14ISC
- -licenseNot gradedqualityDmaintenanceA TypeScript implementation of a Model Context Protocol server and client that enables interaction with language models (specifically Mistral running on Ollama).-
- AlicenseCqualityDmaintenanceA 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.55MIT
- -licenseAqualityNot gradedmaintenanceA comprehensive Node.js server implementing Model Context Protocol (MCP) that enables filesystem operations, process management, and terminal session handling with an enterprise-grade security approach.141,426,013 npm-