terminal-mcp

An MCP server that gives agents real terminals. A client can start shells or programs in a pseudo-terminal, run commands and get back exactly their output and exit code, keep reading output of long-running processes by cursor, type into interactive programs (REPLs, prompts, vim), see whether a session is busy, idle, waiting for input or exited, and terminate a session with its whole process tree.

It works with any MCP client. Local clients launch it over stdio; remote or hosted clients (such as Manus) connect over Streamable HTTP with a bearer token. It serves both the 2025-era protocol and the 2026-07-28 revision.

This recording is npm run demo -- --npx: a scripted MCP client making the same tool calls an agent would, against the published npm package. Every response shown is the server's real answer. Replay it in your terminal with npm run demo, or play docs/demo.cast with asciinema play. For a real agent, see Manus controlling terminals through terminal-mcp, the transcript of a Manus task using the server as a custom MCP connector.

Status

Version 0.1.0 meets all 8 of 8 requirements in the original brief, and 24 of the 45 features in the full product plan are done (53%), with 2 more partly done. Next up: 0.1.1 fixes two small known defects, then 0.2 lets Manus control terminals on your own Mac. ROADMAP.md has the build timeline, the feature-by-feature table and the release plan.

Install from npm

No clone or build needed; the client starts the server with npx:

claude mcp add terminal -- npx -y @ryamgoh/terminal-mcp          # Claude Code

{ "mcpServers": { "terminal": { "command": "npx", "args": ["-y", "@ryamgoh/terminal-mcp"] } } }

The JSON form works for Cursor (~/.cursor/mcp.json), Claude Desktop and most other clients. Add server flags after the package name, for example ["-y", "@ryamgoh/terminal-mcp", "--max-sessions", "8"]. In Manus, a command-based custom MCP connector with npx -y @ryamgoh/terminal-mcp gives the agent terminals in its own cloud sandbox; to give it terminals on your machine, use HTTP mode (below). The server is also listed in the MCP Registry as io.github.ryamgoh/terminal-mcp.

Quick start (from source)

npm install
npm run build
npm test            # 91 end-to-end tests against the built server (bash + zsh, stdio + HTTP)
npm run smoke       # narrated 11-step check of one real session, as a local MCP client sees it
npm run demo        # the narrated demo recorded above (add `-- --npx` to run the published package)

Requirements: Node.js 22.12+ (CI tests 22 and 24), macOS or Linux, bash or zsh. node-pty ships prebuilt binaries for macOS; on Linux it compiles during install (needs python3, make, a C++ compiler). On macOS, install (and server start) restores the execute bit that node-pty 1.1.0 omits on its prebuilt spawn-helper (node-pty#850); without it every spawn fails with posix_spawnp failed.

On a Mac? MACOS.md walks through install, tests, the Inspector, connecting Claude Code, Cursor and Claude Desktop, HTTP mode and Manus, step by step.

Releasing? PUBLISHING.md covers the first release to npm and the MCP Registry, and the tag-driven releases after it.

Connect a client

Claude Code

claude mcp add terminal -- node /absolute/path/to/terminal-mcp/di

... [View full README on GitHub](https://github.com/ryamgoh/terminal-mcp#readme)