Terminal MCP

macOS · MCP server

Let your AI agent drive Terminal.app — safely.

Terminal MCP is a local MCP server for Apple's Terminal. Claude and other MCP clients can list sessions, run commands, and read output in the real Terminal windows on your Mac — while you decide, per session, what they're allowed to touch.

  • Works with the Terminal you already use — real windows, real scrollback, no hidden shells
  • Per-session permissions: block a session, make it read-only, or allow commands
  • One-click pause stops all changes instantly from the menu bar
  • 100% local — a user-only Unix socket, no HTTP server, no cloud, no telemetry
  • Commands are delivered as data, never evaluated or rewritten by the bridge
  • History is off by default; command bodies are never stored without an explicit opt-in
Free download

Version 1.0.3 · macOS 13 Ventura or later · Apple Silicon

Terminal MCP app icon

Nine tools, one clear contract

Every targeted operation requires a bridge-issued session ID, checked again immediately before it runs — an agent can never "accidentally" type into whatever window happens to be active.

terminal_status

Is Terminal running, how many windows, is the bridge paused.

terminal_list_sessions

Every window and tab, with busy state and permissions.

terminal_get_active_session

See what's focused — discovery only, never a command target.

terminal_create_session

Open a fresh Terminal window for the agent to work in.

terminal_send_command

Run a command in one specific, permitted session.

terminal_send_key

Arrow keys, Return, Escape and friends for interactive prompts.

terminal_read_output

Read the visible screen or scrollback, capped at 50,000 characters.

terminal_capture_screen

A read-only screenshot of the session's window.

terminal_focus_session

Bring a session's window to the front.

Built so you stay in charge

Terminal remains the owner of every shell, window, and byte of output. The bridge adds control — it never adds a back door.

No injection, by design

Commands travel as Apple event values into a pre-compiled script — never pasted into script source, never modified, never evaluated by the bridge.

Local-only transport

The MCP helper talks to the app over a current-user-only Unix socket and verifies who's on the other end. There is no URL, port, or remote control surface.

Private by default

Request history is opt-in. Command bodies and output previews each need a separate, explicit opt-in behind a sensitive-data warning — and stay on your Mac.

How to install

1

Download & drag

Grab the DMG, open it, and drag TerminalMCP onto the Applications folder.

2

Grant permissions

Launch the app once. Onboarding walks you through the Terminal Automation permission (plus optional Accessibility and Screen Recording for special keys and captures).

3

Point your MCP client at it

Add the helper as a local stdio server — that's the whole setup. The helper launches the app for you when it's needed.

{
  "mcpServers": {
    "terminal": {
      "command": "/Applications/TerminalMCP.app/Contents/Helpers/terminal-mcp"
    }
  }
}

Privacy. Terminal MCP works fully offline and never collects or transmits anything — no commands, no output, no usage data. The app is notarized by Apple. Questions or problems? Write to support@yjlab.io.

Release notes

1.0.3 2026-07-12

  • Terminal MCP updates itself now. Choose “Check for Updates…” from the Terminal MCP menu — if a newer version is out, the app downloads it, verifies its signature, replaces itself, and relaunches. No more re-downloading from the website. Turn on automatic checking in Settings ▸ General ▸ Updates to be told about new versions as they ship; an update is only ever installed after you approve it.
  • Clearer “Store output previews” setting. The Privacy setting now spells out that previews are captured only for terminal_read_output requests (terminal_send_command records delivery, not results), that enabling applies to new requests only, and that disabling removes previews already stored.

1.0.2 2026-07-11

  • Clearer permission setup. The Permissions section in Settings now shows one row per macOS panel — Accessibility, Automation, and Screen Recording — each with a plain-language note on exactly what to enable there and why (for example, that the Automation panel needs both Terminal and System Events switched on for TerminalMCP).
  • The menu bar’s “Open Permission Settings” matches. It lists the same three panels, without the duplicate Terminal/System Events entries that pointed at the same place.

1.0.1 2026-07-11

  • Automation consent prompts now appear reliably. The app ships with the Apple Events automation entitlement it needs under macOS’s hardened runtime, so the “wants to control Terminal” prompts show up instead of control being silently denied.
  • All permissions are requested up front. After onboarding, the app asks for Terminal and System Events Automation, Screen Recording, and Accessibility in sequence at startup — so an MCP tool call never stalls behind a system prompt mid-request.
  • About panel. Terminal MCP ▸ About shows the version with links to the homepage and support.

1.0.0 2026-07-11

  • Initial release. A local MCP server for Apple’s Terminal.app: nine tools to list sessions, run commands, send special keys, read output, and capture windows — with per-session permissions, a one-click pause in the menu bar, a user-only Unix socket, and history off by default.