TerminalBLOCK
A terminal emulator exposed via MCP for AI assistants
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
Let AI see and interact with your terminal.
Terminal MCP gives LLMs a shared view of your terminal session. Perfect for debugging CLIs and TUI applications in real-time, or letting AI drive terminal-based tools autonomously.
Install
npm install -g @ellery/terminal-mcp
Or via install script:
curl -fsSL https://raw.githubusercontent.com/elleryfamilia/terminal-mcp/main/install.sh | bash
Configure your AI tools
Wire terminal-mcp into the MCP config of every AI tool installed on your machine in one shot:
terminal-mcp setup # detect & install for all detected tools terminal-mcp setup --dry-run # preview without writing terminal-mcp setup --client claude-code,gemini # specific tools only terminal-mcp setup --uninstall # remove the entry from each tool
Supported clients (each gets the right schema for its config format):
A .bak of any pre-existing config is written next to the original on first install. The terminal-mcp entry is added without disturbing other servers or unrelated keys; running setup again is a no-op.
Upgrading
npm install -g @ellery/terminal-mcp@latest
Interactive mode will print a banner on next launch when a newer release is available — terminal-mcp checks the npm registry once per day and caches the result. Headless and MCP
880aaf42aa33OBSERVED · 2026-10-07Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.
claude mcp add terminal-mcp -- npx -y @ellery/[email protected]
{
"mcpServers": {
"terminal-mcp": {
"command": "npx",
"args": [
"-y",
"@ellery/[email protected]"
]
}
}
}Exposed tools (10)
5 read · 4 write · 1 destructive. Blast radius: 1 tool can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
createSession | write | Create a new terminal session and return its metadata. Use the returned sessionId in subsequent type/sendKey/getContent/takeScreenshot calls to address this session. The default session created on first use is separate from sessions created here. |
destroySession | destructive | Destroy a terminal session by ID. The default session cannot be destroyed. |
getContent | read | Get the current content of the terminal buffer |
listSessions | read | List all active terminal sessions, including the default session. Returns session metadata and the configured limits. |
sendKey | write | Send a special key to the terminal (e.g., enter, tab, ctrl+c) |
startRecording | write | Start recording terminal output to an asciicast v2 file. Returns the recording ID and path where the file will be saved. Only one recording can be active at a time. |
stopRecording | write | Stop a recording and finalize the asciicast file. Returns metadata about the saved recording including the file path and duration. |
takeScreenshot | read | Take a screenshot of the terminal. Format |
tool-usage | read | Instructions for effectively using terminal-mcp tools |
type | read | Type text into the terminal |
Trust audit
BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | FAIL |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (7 observation(s))
- Network
- none-observed
- Shell
- declared (1 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (17)
"blocked": ["~/.ssh", "~/.aws"]
"~/.ssh",
"~/.gnupg",
"~/.aws",
"~/.config/gcloud",
destroySession
import { installStdioShutdownHandlers } from "../../dist/utils/shutdown.js";import { installStdioShutdownHandlers } from "../../dist/utils/shutdown.js";@anthropic-ai/sandbox-runtime, @modelcontextprotocol/sdk, @xterm/headless, node-pty, smol-toml, update-notifier, zod, @types/node
- **Read/Write**: Full access (current directory, /tmp, caches)
| **Read/Write** | Green | Full access to read and write |
- **Blocked**: No access (SSH keys, cloud credentials, auth tokens)
4. **Credential protection**: Blocks access to common credential locations by default
The sandbox is most effective when combined with other security practices like least-privilege access and regular credential rotation.
curl -fsSL https://raw.githubusercontent.com/elleryfamilia/terminal-mcp/main/install.sh | bash
curl -fsSL https://raw.githubusercontent.com/elleryfamilia/terminal-mcp/main/install.sh | bash
curl -fsSL https://raw.githubusercontent.com/elleryfamilia/terminal-mcp/main/install.sh | bash
Gates applied: no_behavioural_pass.
880aaf42aa33full audit observations/trust-audit/mcp-server/elleryfamilia__terminal-14.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-07 | 880aaf42aa33 | BLOCK | D | 69 | first audit |
Questions
What is the Terminal MCP server?
A terminal emulator exposed via MCP for AI assistants
What tools does Terminal expose?
10 in total: 5 read-only, 4 that write, and 1 that can delete or overwrite (destroySession). Every one is listed on this page with its risk.
Is Terminal safe to connect to an agent?
No — not without reading the findings first. The audit graded it D (69/100) and found 5 critical or high issues in the source. Each one is listed on this page with the file and line it is on. Separately from the audit: 1 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does Terminal need?
No credential environment variables were found in its source, so it appears to need none.
How does Terminal run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as @ellery/terminal-mcp at 0.5.1.
How current is this page?
The grade is for one exact copy of the source (880aaf42aa33), read on 2026-10-07. The repository is watched and re-audited when it changes.