TerminalMCP

Give your AI agent a real terminal — and stop paying for it in tokens.

A zero-dependency MCP server that hands an AI complete control of a machine — shell, filesystem, git, package managers, processes, network, a real browser and the screen itself — plus optional plugins for the places that work actually gets reported: Discord, Telegram, and FiveM servers. Built so the whole thing costs a fraction of the tokens a naive tool server burns.

git clone https://github.com/Fonlogen/TerminalMCP && cd TerminalMCP
./start.sh --doctor          # or: start.cmd --doctor  on Windows

No npm install. No build step. No dependencies. Just Node 18+.

The problem this solves

Most shell MCP servers expose run_command and stop there. That works, and it is ruinously expensive, because of something easy to miss:

Tool schemas are re-sent to the model on every single request.

On this server's full profile that is ~11,500 tokens of JSON schema per call. An agent that runs five commands one at a time pays it five times — roughly 57,000 tokens of schema, where one batched call would have spent 11,500 — plus the whole conversation, re-sent five times instead of once. The five commands themselves were under 600 bytes.

So token efficiency here is not a nice-to-have that got bolted on. It is the constraint the whole design answers:

Everything else — 28 tools, two transports, cross-platform shells — exists so the agent never has to fall back to an expensive pattern to get something done.

Related MCP server: Bridge Agent MCP

Quick start

1. Check the environment

./start.sh --doctor          # Linux / macOS / Git Bash / WSL
start.cmd --doctor           # Windows

--doctor reports the platform, which shells it found, the working directory, the active limits and what the current tool profile costs per request.

2. Register it with your client

node bin/terminalmcp.js --print-config

That prints ready-to-paste snippets with the correct absolute path. In short:

claude mcp add terminal -- node "/absolute/path/to/TerminalMCP/bin/terminalmcp.js"

{
  "mcpServers": {
    "terminal": {
      "command": "node",
      "args": ["C:\\path\\to\\TerminalMCP\\bin\\terminalmcp.js"],
      "env": { "TERMINALMCP_SHELL": "gitbash" }
    }
  }
}

{
  "servers": {
    "terminal": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/TerminalMCP/bin/terminalmcp.js"]
    }
  }
}

3. Install the skill (optional, recommended)

npm run install-skill                      # → ~/.claude/skills/terminalmcp
node scripts/install-skill.mjs --project    # → ./.claude/skills/terminalmcp

The bundled skill teaches the model how to use the server cheaply — which tool to reach for, when to batch, how to avoid reading whole files. Without it the tools still work; with it they get used well.

What this makes possible

Concrete things that are awkward or impossible with a bare run_command:

Autonomous build-test-fix loops. shell_bulk runs a whole pipeline with conditions and retries in one call, so the agent plans the sequence up front instead of narrating it step by step:

{
  "cwd": "/srv/app",
  "capture": "on_failure",
  "steps": [
    { "id": "deps",  "command": "npm ci" },
    { "id": "test",  "command": "npm test", "timeout_ms": 600000 },
    { "id": "build", "command": "npm run build", "when": "step.test.ok" },
    { "id": "deploy", "command": "./deploy.sh",
      "when": "step.build.ok", "retry": { "count": 2, "delay_ms": 5000 } },
    { "id": "smoke", "command": "curl -fsS localhost:8080/health",
      "when": "step.deploy.ok", "delay_before_ms": 3000,
      "retry": { "count": 5, "delay_ms": 2000 } }
  ]
}

capture: "on_failure" means: silence while everything passes, full output exactly where it broke.

Running dev servers and long builds without blocking. Start it in the background, then read new output with a single blocking call instead of a polling loop:

shell_exec_async { command: "npm run dev", name: "dev" }   → job_id=job1
shell_job { action: "output", job_id: "job1", wait_ms: 30000, offset: 4096 }

Driving a remote machine. The same server speaks HTTP, so an agent can operate a build box, a NAS or a VPS from anywhere on your network.

Working in repos it has never seen. project_info returns languages, package manager, dependencies, frameworks, scripts, entry points, likely test/build commands and git state in one call.

Carrying state between calls. Capture a value once and reference it forever, without it travelling back through the conversation:

shell_exec { command: "git rev-parse --short HEAD", assign: "sha" }
shell_exec { command: "docker build -t app:${vars.sha} ." }

Using secrets without exposing them. A variable marked secret: true works everywhere ${vars.…} works but is never echoed back — not in listings, not in results, not in the audit log.

Testing the web app it just changed. It drives a real browser over the DevTools Protocol — the same protocol Playwright is built on, with no driver to install and no browser to download — and reads a page as a short list of things it can act on rather than as HTML:

browser { action: "launch", url: "localhost:3000" }
browser { action: "snapshot" }
    e4   email     "Email"  name=user  placeholder="you@example.com"
    e5   password  "Password"  name=pass
    e8   button    "Sign in"
browser { action: "fill", ref: "e4", text: "ada@example.com" }
browser { action: "fill", ref: "e5", text: "hunter2", press_enter: true }
browser { action: "screenshot" }              it can see the result
browser { action: "console", level: "error" } and read what the page complained about

Or attach to the browser already open on the desktop — its profile, its extensions, its logged-in sessions. No extension to install: start Chrome once with --remote-debugging-port=9222 and the agent can drive the session you are already signed into.

Seeing what is on the screen. Desktop capture, for everything that is not a web page — a native app, an installer, a chart in a viewer — plus view, which turns any image already on disk into something the model can actually look at:

screen { action: "shot" }                                    the whole desktop
screen { action: "shot", mode: "window", window: "Figma" }   one window
screen { action: "shot", mode: "region", x: 0, y: 0, width: 900, height: 240 }
screen { action: "view", path: "designs/mockup.png" }

Acting on what you see. Some software has no other way in: an installer with no silent switch, a launcher, a native dialog, a legacy admin panel. The loop is capture, decide, act, capture again — and shot: true makes the last two one call:

screen { action: "windows" }                                  what is open
input  { action: "click", x: 812, y: 455, window: "Setup", shot: true }
input  { action: "type", text: "D:\\Games\\server" }
input  { action: "key", keys: "enter", shot: true }

Once the coordinates are known, the whole sequence is one call:

input_bulk { window: "Setup", delay_ms: 150, steps: [
  "click 812 455", "type D:\\Games\\server", "key enter",
  { action: "wait", ms: 1500 }, "shot" ] }

Closing the loop with a person. The work is only finished when somebody knows about it. Optional plugins put the result where they already are — and wait blocks until they answer, so asking a question costs one call rather than a polling loop:

screen   { action: "shot", mode: "window", window: "Grafana" }
telegram { action: "send_file", path: ".terminalmcp/shots/…png", caption: "before the fix" }
telegram { action: "updates", wait: 120 }      blocks until they reply

Running a game server. The fivem plugin answers "is it up and who is on it" with no credentials at all, then drives the rest over RCON or txAdmin — including the F8 client console, which is where client-side script errors actually appear:

fivem { action: "status" }
fivem { action: "resource", resource: "esx_ambulancejob", op: "restart" }
fivem { action: "f8", errors: true }

The four ideas that make it different

1. Batching — shell_bulk

One call, many commands, with real control flow. Each step supports:

Conditions are a real (if small) expression language, evaluated by a dedicated parser — no eval, no access to arbitrary functions:

prev.ok                                    the step before succeeded
prev.exit == 0 && contains(prev.stdout, "0 failing")
step.build.ok && !step.lint.ok             by step id
steps[0].exit == 0                         by position
vars.branch == "main"
failed_count == 0

Shorthands: always, never, prev_success, prev_failure, all_success, any_failure. Functions: contains, icontains, matches, empty, exists, len, lines, first_line, last_line, int, num, lower, upper, trim. Operators: == != > < >= <= && || !, plus =~ / !~ for regex and and / or as words.

tool_bulk — the same, for every tool

shell_bulk batches commands and input_bulk batches clicks; tool_bulk batches anything. Each step names a tool and passes it the arguments it would get on its own, and goes through the very same handler — same guards, same readOnly, same audit log:

tool_bulk { steps: [
  { id: "rd", tool: "file_read", args: { path: "src/app.js", match: "TODO" } },
  { tool: "file_edit", args: { path: "src/app.js", ops: [{ type: "replace_text", old: "v1", new: "v2" }] },
    when: "contains(step.rd.output, \"TODO\")" },
  { id: "t", tool: "shell_exec", args: { command: "npm test" }, capture: "on_failure" },
  { tool: "git", args: { action: "commit", message: "bump to v2", all: true }, when: "step.t.ok" },
  "shell_info"
] }

• Runner fields: id, when, delay_before_ms / delay_after_ms, retry, on_failure, capture (full / on_failure / none), assign; run-wide delay_ms, stop_on_failure, max_output_bytes, max_total_bytes, max_images.

• A step fails when its tool throws, when a shell_exec exits non-zero, or when its ok_if expression (over output and exit) is false. A policy refusal always stops the run.

• Later steps can read prev.output, step.<id>.output, step.<id>.ok and vars.<name> — in when, and in exactly the fields that tool already expands ${...} in (the table in src/tools/interpolate.js).

• assign keeps a step's text output in the variable store; on a shell_exec step it keeps only the trimmed stdout.

• Screenshots any step returns are attached, newest kept up to max_images (default 4).

• Checked up front: an unknown or disabled tool, a nested tool_bulk or a broken condition is refused before the first step runs.

2. Server-side variables

Values the agent captures can stay on the server. Store once, reference as ${vars.<name>} in any later call — the value itself never returns to the conversation.

vars { action: "set", name: "api", value: "https://api.example.com" }
vars { action: "list" }          names, types, sizes — never full values
vars { action: "get", name: "api" }
vars { action: "load", name: "conf", path: "config.json", json: true }

Three tools write straight into the store: shell_exec assign, http_request assign, and per-step assign in shell_bulk and tool_bulk.

${...} expands in commands, cwd, env values, stdin, file paths, URLs, request headers, query params, git messages and refs, and every bulk step. Deliberately not in file content, regex patterns or patch bodies — a JavaScript template literal, a GitHub Actions workflow and a regex all legitimately contain ${...}, and rewriting them silently would be worse than asking. The eligible fields are declared in a single table (src/tools/interpolate.js) rather than scattered across handlers, so the expansion surface is auditable at a glance.

It does not fight the shell. ${...} is shell syntax too. Anything that does not name a variable the server knows is passed through untouched, so echo ${HOME}, ${PATH%%:*} and ${#arr} reach bash intact. A ${vars.typo} that looks like ours but matches nothing is passed through literally and reported in the result, so a mistyped name reads as a mistake rather than becoming a silent empty string.

3. Tool profiles

Since schemas cost tokens on every request, you choose how many you want to carry. Measured on this repo:

node bin/terminalmcp.js --tools core             # shell, jobs, bulk, files, vars
node bin/terminalmcp.js --tools dev              # + search, git, fs, dev, data
node bin/terminalmcp.js --tools web              # + browser, screen, net, search
node bin/terminalmcp.js --tools core,git,search  # pick groups
node bin/terminalmcp.js --tools all,-browser     # everything except one

core and vars are always included. --list-tools and --doctor print the cost of every group, and shell_info reports it to the model at runtime — so trimming is an informed decision rather than a guess. Nothing is ever lost: whatever isn't exposed as a tool is still reachable through shell_exec.

4. Reading a web page without reading its HTML

Handing a model 400KB of markup to find a login button is the browser equivalent of cat-ing a whole file to find one function. So the primary way to read a page is snapshot: every element you can actually act on, named the way a person would name it, each with a short ref.

browser { action: "snapshot" }

https://example.com/login  —  Example — Sign in

e1   h1         "Sign in to Example"
e2   link       "Forgot your password?"  -> /reset
e3   email      "Email"  name=user  placeholder="you@example.com"  required
e4   password   "Password"  name=pass
e5   select     "Free Pro"  name=plan  options=["free","pro"]
e6   checkbox   "Remember me"  name=remember  unchecked
e7   button     "Sign in"

Then click { ref: "e7" }. A few hundred tokens for a page instead of tens of thousands — and it survives a redesign of the markup, which a hand-written CSS selector does not. Refs live in the page itself, so navigating away invalidates them and a stale ref says so rather than quietly clicking the wrong thing.

html is still there for when you genuinely need the markup, with clean: true to drop scripts, styles and comments first.

The same logic applies to images. A vision model is billed by area — roughly width × height / 750 tokens — so a raw 4K screenshot is about 11,000 tokens and the same screenshot at 1200px wide is about 1,100 and just as readable. Every capture is therefore scaled to max_width (1200 by default) before it is returned, and the reply tells you what that cost:

viewport of http://localhost:3000/
saved .terminalmcp/shots/2026-04-11_18-22-03.png (184320 bytes, 1280x800)
1280x800 scaled to 1200x750, ~1200 image tokens

Tool reference

28 tools in 13 groups. Most use an action parameter rather than one tool per verb — git alone would otherwise be twenty tools, and browser thirty.

core — always on

vars — always on

search

git

One tool, ~30 actions, compact output, plus action: "raw" for anything not covered.

Read: status, log, diff, show, blame, branches, tags, remotes, stash_list, file_history, current, root, config_get Write: add, unstage, commit, checkout, branch_create, branch_delete, merge, rebase, reset, revert, restore, stash, stash_pop, tag_create, fetch, pull, push, apply, clean, init

git is invoked directly rather than through a shell, so a commit message containing quotes, newlines or $ needs no escaping.

fs

archive

sys

net

dev

data

watch

browser

One tool, thirty actions, driving Chrome / Chromium / Edge / Brave over the DevTools Protocol.

Every element target accepts one of three things: ref from the last snapshot (cheapest and sturdiest), selector for a CSS selector, or text to find an element by what it says. Ambiguous text prefers the thing you can act on and the innermost match, so text: "Sign in" picks the button rather than the heading above it that says the same words.

Downloads

A download is the one thing a browser does that produces no page, which is why it used to look broken: navigating to a file URL aborts its own navigation — Chromium hands the bytes to the download manager and no document is ever committed — so navigate reported a failure while the file was, in fact, arriving.

browser { action: "download", url: "https://example.com/pack.zip" }
browser { action: "download", text: "Download release" }     a link or button
browser { action: "download" }                    just wait for what the page started
browser { action: "downloads", wait: true }

download blocks until the file is on disk and answers with its real name, its size and its path. The point is the session: a file behind a login comes down with the cookies the browser already has, which is the whole reason not to reach for http_request. navigate now recognises a download too, instead of reporting a navigation failure.

Files land in .terminalmcp/downloads (configurable with browser.downloadDir), named by what the server suggested — sanitised, because a Content-Disposition filename is attacker-controlled input, and never overwriting: a second pack.zip becomes pack (2).zip.

Browsers are found automatically: the usual install locations per platform, then $CHROME_PATH, then a Playwright or Puppeteer cache if you already have one on disk. Nothing is downloaded.

screen

Captures are saved at full resolution and shown scaled to max_width, so the file on disk stays the good copy while the reply stays cheap.

When every shot fails but displays and windows work

That combination is not a broken tool — it is the signature of a process that can see the desktop's furniture but not its pixels. Enumerating monitors and windows works from any session; copying pixels needs the interactive desktop, which a Windows service, a scheduled task, session 0 and an SSH/WinRM login do not have.

screen { action: "probe" }

reports the window station (only WinSta0 can capture), the Windows session id, the PowerShell version, and the result of a one-pixel test capture with the exact exception — then tries a real 8×8 capture end to end. The fix is almost always to start the server from a terminal inside your own logged-in session.

input

Two things make it usable rather than merely present:

• shot: true returns a screenshot taken straight after the action, so one call both acts and shows the result. Acting blind and then capturing is two calls and a race.

• window raises that window first. Input follows the focus, and the window that had focus is not always the one you meant — this is the difference between typing a path into an installer and typing it into somebody's chat.

input { action: "key", keys: "ctrl+shift+esc" }      a chord
input { action: "key", keys: "alt+f x" }             a sequence, in order
input { action: "key", keys: "w", hold_ms: 800 }     held down, not tapped
input { action: "type", text: "città" }              characters, not keystrokes
input { action: "drag", x: 100, y: 100, to_x: 400, to_y: 300 }

readOnly blocks all of it. position and probe still answer.

input_bulk — a whole sequence in one call

What shell_bulk is to commands, input_bulk is to the mouse and keyboard. Steps run in order and take every input action, plus shot (a screenshot, any screen mode) and wait:

input_bulk {
  window: "Notepad",            raised once, before step 1 — if it cannot be, nothing is sent
  delay_ms: 150,                pause between steps (default 100): UIs need a beat
  final_shot: "on_failure",     a picture of where it broke
  steps: [
    "key ctrl+n",
    "type Hello from TerminalMCP",
    { action: "key", keys: "ctrl+s", delay_after_ms: 800 },
    { id: "dlg", action: "shot", mode: "window", window: "Save as" },
    "type C:\\temp\\hello.txt", "key enter"
  ] }

• Strings are shorthand: "click 400 300", "click", "move 10 20", "scroll -3", "type …", "key ctrl+s", "focus Title", "wait 500", "shot", "position".

• Delays: delay_ms between steps, and per step delay_before_ms / delay_after_ms, and wait as a step of its own.

• Flow: when, on_failure, retry and stop_on_failure work as in shell_bulk, reading prev.ok, step.<id>.ok, vars.<name>. A position step exposes step.<id>.x / .y, and numeric fields accept "${…}", so a later step can click where the pointer was.

• Checked before it starts: an unknown action, a misspelt key chord, a type with no text or a drag with no destination is refused before the first event is sent. So is the whole run under readOnly, unless it only waits.

• Images are capped at max_shots (default 4). Past the cap the oldest pictures are dropped first, and the report says which ones.

What "HID" does and does not mean here

Input is synthesised by the operating system — SendInput on Windows, xdotool on X11, osascript or cliclick on macOS. Applications receive those events through the same path as real ones and cannot tell the difference.

What they are not is physical. Software that reads raw HID and deliberately checks — which is what anti-cheat does — can refuse injected input, and no setting changes that. A game that ignores this needs a microcontroller presenting itself as a real USB keyboard, which is a different backend and not a flag. Everything that is not actively looking for injection works.

Wayland refuses input injection by design; there ydotool (pointer, via /dev/uinput) and wtype (keyboard) are the way through, and probe says which of them is installed. An X11 session needs only xdotool.

macOS: why the pointer does not go through AppleScript

The obvious route is tell application "System Events" to click at {x, y}, and it is a trap. That is an accessibility command asking the application to click for itself; when the coordinates resolve to no UI element it can simply never answer. The Apple event sits there until something kills it — no error, no refusal, nothing on stderr, and no TCC prompt. Granting Accessibility does not change it, which is what makes it so hard to diagnose: every permission looks correct and the call still hangs.

So the pointer goes through CGEventPost instead — the same path a real mouse takes — reached with osascript -l JavaScript and the Objective-C bridge, which ships with macOS. Nothing to install. cliclick is still used when it is present, because it is battle-tested, but it is no longer required for moves or drags.

Accessibility is still needed, and it belongs to the application that launched the server — the terminal, the editor, the Claude app — not to node, which merely inherits it. When the grant is missing, macOS does not refuse a posted event: it drops it silently. probe therefore posts a one-pixel move and checks whether the pointer actually moved, which is the only way to tell the two apart from the outside.

Everything still on System Events — typing, key chords, raising a window — now carries with timeout of, so a hung Apple event comes back as an error rather than as twenty seconds of silence.

Every failure the Windows side can hit comes back named rather than as a generic "capture failed": no interactive desktop, a temp directory that cannot be written, a pwsh install without the Windows Desktop runtime, a minimized window (pass activate: true), a title that matches nothing. And a web page never needs a desktop at all — browser screenshot renders headlessly, including the full scrolling page.

Optional plugins

Three integrations ship with the server and none of them are on by default. That is the same logic as tool profiles: a schema in the model's context costs tokens on every single request, and most sessions have no business talking to Discord.

node bin/terminalmcp.js --plugin discord
node bin/terminalmcp.js --plugin fivem --plugin telegram

or in the config file:

{ "plugins": ["fivem", "telegram"] }

A plugin is never part of all — naming it is what enables it. Once loaded it behaves like any other group, so --tools all,-telegram still removes it, and --doctor reports whether it is actually configured:

plugins
  fivem     server 10.0.0.5:30120, rcon password set, txAdmin http://10.0.0.5:40120 (env token)
  telegram  token set (…4f2a), default chat -1001234567890

Credentials

Secrets never have to live in the config file. Any string value may be written "env:NAME" and is read from that environment variable instead:

{
  "plugins": ["telegram"],
  "pluginConfig": {
    "telegram": { "token": "env:TELEGRAM_BOT_TOKEN", "defaultChat": "-1001234567890" }
  }
}

An unset variable is reported as not configured, with instructions — not as a mysterious 401 three calls later.

Every plugin registers its secrets with a redactor, and everything it returns passes through it. This matters more than it sounds: the Telegram Bot API puts the token in the URL, so a naive error message publishes it to the transcript and the audit log. Here it comes back as <redacted>, and there is a test that fails if it ever does not.

fivem — FiveM / RedM servers

Four different things get called "the console", and the plugin is explicit about which is which.

inspect: which files of a resource can actually be read

Most paid FiveM resources ship through Cfx.re asset escrow. The scripts are encrypted, the server decrypts them at runtime, an .fxap file sits in the resource root, and the manifest lists under escrow_ignore the files the author left in the clear — normally the config and whatever is meant to be edited.

That list is the entire readable surface of the resource, and nothing about reading the rest fails: file_read succeeds, bytes come back, and thousands of tokens buy ciphertext. search_text across the folder is worse, because it reads every encrypted file to match nothing.

fivem { action: "inspect", resource: "esx_policejob" }
fivem { action: "inspect" }        every resource under the cwd, at a glance

esx_policejob — ESCROWED
D:\Server\resources\[esx]\esx_policejob
fxmanifest.lua, fx_version cerulean, game gta5
an .fxap file is present; escrow_ignore lists 3 pattern(s); it depends on '/assetpacks'

readable — 5 file(s):
  config.lua                                    4.7 KB
  client/cl_open.lua                            1.0 KB
  …
encrypted — 4 script(s), do not read:
  client/cl_main.lua, server/sv_main.lua, …

It distinguishes ESCROWED — an .fxap is present, so this build really is encrypted — from ESCROW-READY, where the manifest declares escrow_ignore but no .fxap is there, which is what the source copy looks like and is entirely readable. Claiming the first when it is the second would send someone hunting for ciphertext that does not exist, so it says which one it found and how to settle it.

The skill tells the model to run this before opening any file of a resource.

Two honest notes rather than marketing:

• If TerminalMCP started the FXServer, don't use RCON. shell_exec_async + shell_job gives you its real stdout and stdin — nothing to lose to a dropped datagram, and you can type into it. The plugin says so in its own error messages.

• Only /host/status is a documented txAdmin API. The other tx_* actions drive txAdmin's own panel interface, which can change between versions. They work, they are tested against the shapes txAdmin's source actually uses, and they will tell you plainly when a version has moved underneath them.

Typing into a player's F8 console is not something any remote protocol can do — so an optional in-game resource ships in plugins/fivem/resource/. Install it and f8_exec runs a command in a chosen player's console for real, while client_lua and server_lua evaluate Lua and hand back the value:

fivem { action: "client_lua", player: "3", lua: "GetEntityCoords(PlayerPedId())" }

Read its README before installing it. It grants arbitrary Lua execution on your server and on connected clients to whoever holds its secret. That is the feature, and it is not for every server.

One thing to know because it is the easiest way to lose an afternoon: FiveM routes an HTTP request to a resource by the first path segment, which is the resource's folder name — not the name in fxmanifest.lua. If you install the bridge under a different folder name, set bridge.resource to it. fivem { action: "bridge" } reads the server's own resource list when it cannot connect, and tells you which name to use.

discord

Works with a bot token, a webhook URL, or both. A webhook needs no application and no permissions but can only post; a bot can read, edit, react and list.

discord { action: "send", text: "Deploy finished: 3 services updated" }
discord { action: "upload", path: "build.log", caption: "the failure" }
discord { action: "read", limit: 20 }
discord { action: "wait", wait: 60 }          blocks until someone replies

@everyone and role pings are suppressed unless you pass mentions: true. A tool that can ping four thousand people by accident is a bad tool.

Rate limits are handled: a 429 is answered by waiting exactly as long as Discord asks, once.

telegram

telegram { action: "send", text: "Backup finished, 4.2GB in 6m12s" }
telegram { action: "send_file", path: "shot.png", caption: "the dashboard" }
telegram { action: "updates", wait: 60 }

updates uses Telegram's own long polling, so it returns the instant a message arrives rather than on a timer, and the read offset is kept server-side — each message reaches you exactly once.

Writing your own

A plugin is an ES module exporting TOOLS and createHandlers — the same shape as src/tools/*.js. There is no plugin API to learn beyond that. Point at it by path:

{ "plugins": ["./my-plugins/jira.js"] }

Two extras are worth declaring. MUTATING_ACTIONS lists the actions that change something outside this machine, and readOnly then refuses them centrally rather than in each handler. describe() returns the one line --doctor prints, so "is this thing configured" is answerable without making a call.

A plugin that fails to load is reported on stderr and skipped. It never stops the server — everything else on the machine still works.

Transports

stdio (local, default)

The normal way to run an MCP server. Your client spawns the process and talks over stdin/stdout.

HTTP (remote)

The same server can run as a network service. There is no authentication — see Security before exposing it.

./start-http.sh                  # 0.0.0.0:8787, reachable from other machines
start-http.cmd                   # same, on Windows
PORT=9000 ./start-http.sh

./start.sh --http                # local only (127.0.0.1:8787)
node bin/terminalmcp.js --http --host 0.0.0.0 --port 8787

./start-http-tunnel.sh           # + a public URL through Cloudflare, all tools
start-http-tunnel.cmd            # same, on Windows

A public URL, without touching the router

--tunnel starts the server and asks Cloudflare for a throwaway hostname under trycloudflare.com, connecting to it outbound. No account, no DNS, no port forwarding — which is the whole appeal when the machine is behind NAT or a firewall somebody else administers.

node bin/terminalmcp.js --http --tunnel --tools all

  ============================================================
   PUBLIC URL   https://brave-lemon-rally-pine.trycloudflare.com/mcp
   legacy SSE   https://brave-lemon-rally-pine.trycloudflare.com/sse
   health       https://brave-lemon-rally-pine.trycloudflare.com/health
  ------------------------------------------------------------
   claude mcp add --transport http terminal https://brave-...com/mcp
  ------------------------------------------------------------
   ANYONE WITH THIS URL HAS A SHELL ON THIS MACHINE.
  ============================================================

It needs cloudflared on PATH — winget install --id Cloudflare.cloudflared, brew install cloudflared, or the binary from its releases. --doctor says whether it was found, and --cloudflared <path> points at a specific one.

Three things worth knowing before using it:

• The URL is public and there is no authentication. It is random, but random is not secret: it travels wherever you paste it, and one paste into the wrong window is enough. A quick tunnel is for a session, not for leaving up.

• The hostname changes every run. Quick tunnels are ephemeral by design; a stable hostname needs a named tunnel and a Cloudflare account, which is a different feature and not this one.

• --tunnel binds 127.0.0.1 unless --host says otherwise. cloudflared reaches the server locally, so the port does not need to be open on the local network as well — one fewer way in, for free.

A tunnel that cannot be opened is reported and otherwise ignored: the server keeps serving locally rather than failing to start. start-http-tunnel enables every tool group, which is a lot of schema — if a tool goes missing in your client, that is the truncation described above, and --tools web is the fix.

Both MCP HTTP transports are served at once, so current and older clients work against the same port:

claude mcp add --transport http terminal http://<ip>:8787/mcp
curl http://<ip>:8787/health
node bin/terminalmcp.js --print-config --http --host 0.0.0.0

Sessions. initialize issues an Mcp-Session-Id, returned as a header and echoed back by the client. Each session keeps its own negotiated protocol version, so clients on different MCP revisions can talk to one server simultaneously. Idle sessions expire after 30 minutes. By default an unknown session id is still served rather than 404'd — nothing here is authenticated, so strictness would only break clients that forget the header; --strict-sessions turns that on.

Shared state, deliberately. Jobs and variables are shared across sessions, because this server drives one machine: a job started by one client stays readable from another, and from the same client after a reconnect.

Long commands. HTTP-level timeouts are disabled, so a ten-minute command isn't cut off. Behind a reverse proxy that closes idle responses, add --sse-replies for keepalive comments — though shell_exec_async plus shell_job is the better answer regardless.

Configuration

Precedence, strongest first: per-call parameters → TERMINALMCP_* environment variables → config file → defaults.

The config file is looked up in this order:

1. $TERMINALMCP_CONFIG

2. ./terminalmcp.config.json

3. ./.terminalmcp.json

4. ~/.terminalmcp/config.json

cp terminalmcp.config.example.json terminalmcp.config.json

// comments and trailing commas are tolerated.

Choosing a shell

"auto" picks the system default: pwsh → powershell → cmd on Windows, $SHELL then bash → zsh → sh elsewhere.

Custom shells can be named and then selected per call:

{
  "shells": {
    "docker": { "command": "docker", "args": ["exec", "-i", "web", "sh", "-c"] }
  }
}

On Windows, cmd and PowerShell commands run via a temporary script file, so multi-line scripts and quoting behave the way you expect.

Main options

Command-line options

node bin/terminalmcp.js --help

--cwd, --shell, --config, --timeout-ms, --max-output-bytes, --login, --tools, --vars-file, --persist-secrets, --max-vars, --max-var-bytes, --read-only, --allowed-root, --log-file.

Browser and screen: --browser-path, --no-headless, --shots-dir, --max-image-width.

Plugins: --plugin <name|path>, repeatable.

HTTP: --http, --host, --port, --path, --no-cors, --strict-sessions, --sse-replies, --max-body-bytes.

Commands: --doctor, --print-config, --list-tools, --help, --version.

Environment variables

TERMINALMCP_SHELL, TERMINALMCP_CWD, TERMINALMCP_TIMEOUT_MS, TERMINALMCP_MAX_OUTPUT_BYTES, TERMINALMCP_LOGIN, TERMINALMCP_KEEP_ANSI, TERMINALMCP_READ_ONLY, TERMINALMCP_LOG_FILE, TERMINALMCP_ALLOWED_ROOTS, TERMINALMCP_CONFIG, TERMINALMCP_TOOLS, TERMINALMCP_VARS_FILE, TERMINALMCP_BROWSER_PATH, TERMINALMCP_BROWSER_HEADLESS, TERMINALMCP_SHOTS_DIR, TERMINALMCP_PLUGINS, TERMINALMCP_HTTP, TERMINALMCP_HTTP_HOST, TERMINALMCP_HTTP_PORT, TERMINALMCP_HTTP_PATH, TERMINALMCP_HTTP_CORS.

Plugins also read their own conventional variables when the config says so: TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, DISCORD_WEBHOOK_URL, FIVEM_RCON_PASSWORD, TXADMIN_PASSWORD, TXHOST_API_TOKEN, FIVEM_BRIDGE_SECRET.

Security

Be clear-eyed about what this is. TerminalMCP gives an AI the same privileges as the user account running it. There is no sandbox, and that is the point — a sandboxed terminal cannot install a dependency, restart a service or read a log. Run it where you would be comfortable handing someone a shell.

Network exposure

The library default binds 127.0.0.1, because opening up should be a deliberate act. start-http.sh / start-http.cmd bind 0.0.0.0 — they exist for remote use — and the server says so loudly at startup.

There is no authentication, so the port is the credential. Two cheap measures that change a lot:

• Keep it off the public internet. A LAN, a VPN (Tailscale, WireGuard) or an SSH tunnel is enough: ssh -L 8787:127.0.0.1:8787 user@host, then point the client at http://127.0.0.1:8787/mcp while the server stays bound to localhost.

• --tunnel is the deliberate exception: it puts the server on the public internet behind a random hostname, which is convenience bought with exposure. Use it for a session you are watching, not as a deployment, and stop the server when you are done — the URL dies with it.

• On an untrusted network, put a reverse proxy (Caddy, nginx) in front with TLS and Basic Auth. The server neither knows nor cares.

The browser and the screen deserve their own thought

Two of the newer capabilities reach further than a shell does, and it is worth knowing exactly how far.

• browser attach inherits a real session. Attaching to a browser you started with --remote-debugging-port gives the agent that browser's profile: your cookies, your logged-in accounts, your extensions. It can act as you on every site you are signed into. That is precisely why the feature is useful, and precisely why attach should be a decision you make rather than a default. launch is the safer sibling — a throwaway profile that is signed into nothing.

• A screenshot captures whatever is on the screen, including windows that have nothing to do with the task: a password manager, somebody else's chat, a medical record. mode: "region" and mode: "window" exist so a capture can be narrow on purpose.

• readOnly blocks browser launch (it starts a process) and blocks writing captures to disk, but it cannot police what a page does once it is open.

• macOS will ask for permission the first time: Screen Recording for captures, Accessibility for listing windows. Nothing can be captured until you grant it, and the error says so rather than returning a black image.

• The screen tool needs a desktop, and on Windows specifically the interactive one: a service or an SSH login can list windows but not copy pixels. screen { action: "probe" } says which case you are in. On a server, in a container or over plain SSH there is nothing to capture, and it says so — browser screenshots still work there, because they render headlessly.

Plugins reach outside the machine

A shell command affects this computer. Sending a Discord message, kicking a player or restarting a game server affects other people, and cannot be undone by deleting a file.

• Each plugin declares which of its actions mutate, and readOnly refuses exactly those while leaving the read-only ones working. So --read-only gives you a server that can look at your Discord, your Telegram and your game server without being able to say or break anything.

• allowedChannels, allowedChats and the FiveM allowCommands / denyCommands lists narrow what is reachable at all. A refusal is reported as Policy: … so the model knows it was a deliberate setting rather than a bug to route around.

• Discord pings are suppressed unless explicitly allowed.

• Plugin secrets are registered with a redactor and scrubbed from every result and every error, including the audit log.

Optional guardrails

All off by default, because the server's purpose is unrestricted access. Turn them on to narrow capability rather than network:

A refusal reaches the model as Policy: …, so it understands this is an operator decision rather than an error to route around. Guardrails apply uniformly: a git write and a pkg install pass through the same gates as shell_exec, not around them.

Handling of secrets

A variable marked secret: true is usable via ${vars.…} but never returned: listings show (secret), get masks it unless reveal: true, the audit log records <secret>, and it is not written to the store file unless persistSecrets is explicitly enabled.

Architecture

bin/terminalmcp.js        CLI: arguments, --doctor, --print-config, startup
src/server.js             JSON-RPC 2.0, MCP methods, sessions, audit log
src/http.js               HTTP transport: Streamable HTTP + legacy HTTP+SSE
src/exec.js               spawning, timeouts, process-tree kills, buffering
src/jobs.js               background job registry
src/bulk.js               sequential runner: conditions, retries, variables
src/expr.js               the mini-language for `when` and `${...}`
src/vars.js               variable store: TTL, caps, secrets, atomic persistence
src/diff.js               line diff (LCS) and unified-patch application
src/glob.js               glob matching and .gitignore semantics
src/walk.js               one directory walker, shared by every crawling tool
src/archive.js            ZIP and TAR, written by hand
src/files.js              file_read / file_write / file_edit / fs_list
src/ws.js                 a WebSocket client, written by hand (RFC 6455)
src/cdp.js                Chrome DevTools Protocol: discovery, launch, sessions
src/browser.js            page operations: snapshot, input, capture, network
src/image.js              PNG decode / resize / encode, and image token maths
src/screen.js             desktop capture per platform, display and window lists
src/input.js              mouse and keyboard per platform, key tables, chords
src/tunnel.js             Cloudflare quick tunnels: find cloudflared, parse its URL
src/shells.js             shell detection and per-platform invocation
src/config.js             configuration loading and precedence
src/guards.js             optional guardrails
src/plugins.js            plugin loading, secret resolution, redaction
plugins/fivem/            RCON, txAdmin, the F8 log, and an in-game bridge
plugins/discord/          bot REST API and webhooks
plugins/telegram/         bot API with server-side long polling
src/format.js             output cleanup and truncation
src/tools/index.js        registry: groups, profiles, token cost
src/tools/interpolate.js  which fields accept ${...}, declared in one place
src/tools/*.js            one module per tool group
skills/terminalmcp/       the skill that teaches a model to use it well

Roughly 18,000 lines of source, 4,800 lines of tests, zero dependencies.

Implementation notes

• The MCP protocol is implemented by hand (JSON-RPC 2.0, newline-delimited on stdio) specifically to keep the dependency count at zero. Clone and run.

• stdout carries only protocol. Every diagnostic goes to stderr.

• Requests don't block each other. A long shell_exec doesn't stop a concurrent shell_job poll.

• Timeouts kill the whole process group — process.kill(-pid) on POSIX, taskkill /T /F on Windows — so a command that spawned children doesn't leave orphans behind. There's a regression test for exactly that.

• Over HTTP, replies are plain JSON when the client accepts JSON. Clients send Accept: application/json, text/event-stream on every request, so wrapping every short reply in an event stream would buy nothing. SSE is used when the client won't take JSON, or on demand via --sse-replies.

• when and ${...} use a dedicated parser. No eval, no reachable arbitrary functions.

• The browser is driven over a hand-written WebSocket client. Node 22 has a global WebSocket, Node 18 does not, and adding ws for one transport would have ended the zero-dependency promise. RFC 6455 is a handshake plus a frame header; the fiddly part is that a full-page screenshot arrives as one multi-megabyte message, so frames are read from a chunk queue rather than by re-concatenating a growing buffer.

• PNG is decoded, resized and re-encoded in process. Shelling out to ImageMagick would mean the feature silently degrades on machines that do not have it — which is most Windows machines. The encoder picks a row filter per row and drops the alpha channel when nothing is transparent, which takes a flat UI screenshot from 1.4MB of raw pixels to a couple of kilobytes.

• Atomic where it matters. file_edit is all-or-nothing; diff apply refuses a partial patch rather than leaving a half-edited file; the variable store persists via write-then-rename.

Output shaping

Every result passes through the same pipeline, because this is where tokens quietly disappear:

• ANSI escape codes stripped, trailing whitespace trimmed, runs of blank lines collapsed.

• Truncation in the middle, keeping head and tail — errors live at the end of a log — with a note of how many bytes were dropped.

• Empty sections omitted entirely. No stderr: (empty).

• Background job output read incrementally by offset, so bytes already seen never come back.

Testing

npm test                 # 1052 assertions
npm run test:smoke       # stdio protocol, exec, jobs, bulk, files, profiles (101)
npm run test:guards      # guardrails: readOnly, allowedRoots, deny*         (14)
npm run test:tools       # extended tools: search, git, fs, archive, bulk   (172)
npm run test:vars        # variables, interpolation, secrets, persistence    (67)
npm run test:image       # PNG codec, resizing, capture back-end selection   (68)
npm run test:screen      # the screen tool: real captures on a virtual X display (99)
npm run test:input       # the input tool: real clicks and keys, witnessed by xev (146)
npm run test:plugins     # loader + fivem, discord, telegram vs mocks       (183)
npm run test:browser     # a real browser: 32 actions end to end, downloads  (130)
npm run test:http        # HTTP transport: streamable, legacy SSE, tunnel     (72)

The tests spawn the real server and speak MCP to it — over stdio for the main suites, over real HTTP (sessions, SSE, CORS, batching, 413s) for the transport suite. So they cover the handshake, JSON-RPC framing and protocol negotiation, not just internal logic. Fixtures include a synthetic repository and a local HTTP server, so git, pkg, search_text and http_request are exercised against something real.

The browser suite is the same kind of thing rather than a mock: it serves fixture pages over HTTP, launches an actual Chromium, and drives a login form through snapshot, fill, select, click and submit, checking that the page received the values. Two parts degrade honestly instead of pretending:

• No browser installed — the browser suite reports that and exits 0. A missing browser is a missing browser, not a broken server.

• No desktop — when Xvfb is installed, the screen suite starts a virtual X display, puts a window on it and captures it for real: the whole screen, one display, one window, an exact rectangle, saved to disk and viewed back. That is the test that matters, because the bugs live in the commands, not around them. Without Xvfb the suite says so and skips that block, and what remains still runs: the PNG codec, the token maths, the back-end decision table, and — for Windows — the failure protocol, the explanation each failure produces, and the temp path Node and .NET have to agree on.

The plugin suite needs no accounts and no secrets: it stands up local mock servers that speak the real wire formats — including an actual UDP socket that checks the RCON packet byte for byte, and a Telegram mock that holds a long poll open until a message arrives. It asserts the things that would be embarrassing to get wrong: that a token never appears in an error, that readOnly refuses exactly the outward-facing actions, and that an allow-list refusal happens before anything goes out on the wire.

When tools go missing in your client

The server logs what it exposes; the client decides what it keeps. Those two numbers can disagree, and nothing in the protocol reports it.

Seen in the wild: a server reporting tools=29 while the client listed 26. The three missing ones were the last three in the list — the tail had been dropped silently, at around 41 KB of accumulated schema. The server was sending all of them, over a working transport, as valid JSON.

So when a tool you expect is not there:

node bin/terminalmcp.js --list-tools     # what the server exposes
curl localhost:8787/health               # the same, over HTTP

If those show the tool and your client does not, the client dropped it. Two things fix it, both about making the list smaller:

--tools all,-browser        # drop the biggest single tool (~6 KB)
--tools core,screen,fivem   # or name only what this session needs

Groups are sent in the order you name them. --tools screen,git puts screen first, so it survives a client that truncates; all and the bundles keep registry order. That ordering is the only lever you have over which tools live through a cap you cannot see, so it belongs to you rather than to the registry.

The server prints a note at startup once the schema passes 40 KB, so this is signposted rather than discovered.

Compatibility

The browser paths are tested on Linux against a real Chromium, and the Windows and macOS browser paths use the same protocol code — only the search for the binary differs per platform. Desktop capture is the one part where the per-platform commands differ substantially: the Linux ones are now captured for real against a virtual X display, and the PowerShell script is parsed and its failure protocol exercised by an actual PowerShell — but a successful Windows capture, and every macOS capture, still depend on a machine we cannot run here. If one misbehaves, please open an issue: screen { action: "probe" } output is the useful thing to paste.

Things worth knowing

• Every command runs in a fresh shell. cd, export and source do not carry across calls or bulk steps. Use cwd, env, or chain inside one command string (cd x && make).

• Output is middle-truncated at maxOutputBytes. Raise it if you genuinely need the middle of a long log, or read the log file with file_read { tail_lines: n } instead.

• search_text honours .gitignore by default. Pass respect_gitignore: false when you're looking for something in build output.

• code outline is pattern-based, not a real parser. It's for orientation; file_read is the source of truth.

• Browser refs are invalidated by navigation, deliberately: they live in the page as window.__tmcpRefs, so a reload or a new URL makes them stale and using one then says exactly that. Call snapshot again.

• JavaScript dialogs are answered automatically (accept by default), else the page would sit frozen forever waiting for a click nobody can make. The message is kept and reported, since an unexplained alert() is usually the reason something appeared not to work.

• Only a browser this server launched is ever closed by it. close on a browser you attached to disconnects and leaves it running; killing the browser a person is using would be unforgivable.

• Screenshots and downloads land under .terminalmcp/ in the working directory. Worth adding to .gitignore — this repo already does.

• A JPEG screenshot is scaled by the renderer rather than afterwards, because this server can resize PNG but not JPEG. That also means the saved JPEG is the scaled one, while a saved PNG is full resolution.

Roadmap

• Parallel step groups in shell_bulk

• Persistent shell sessions (keeping cd / export state)

• Mouse and keyboard control of the desktop, not just capture of it

• Firefox via WebDriver BiDi, alongside CDP

• The Discord gateway, for push delivery instead of polled wait

• A SQL client

• An optional token for the HTTP transport

Contributions and issues are welcome. The test suite is the contract: if you add a tool, add assertions that drive it through the real server.

License

MIT