Canonical URL: https://heyclau.de/entry/mcp/iterm-mcp
Source URLs: https://github.com/ferrislucas/iterm-mcp/blob/main/README.md, https://github.com/ferrislucas/iterm-mcp
Brand: iTerm MCP
Brand domain: github.com
Safety notes: iTerm MCP gives Claude direct access to the active iTerm2 terminal session., The README states that the server has no built-in command safety restrictions and does not evaluate command risk., The write_to_terminal tool can run shell commands, paste multiline input, interact with REPLs, trigger builds, modify files, start network tools, or run destructive commands., The send_control_character tool can send Control-C, Control-Z, Escape, telnet escape, and other control characters that interrupt or alter running processes., The source uses AppleScript through osascript to write text to iTerm2, read the active session buffer, retrieve the TTY, and send control characters., The model may not know whether a command succeeded until it reads terminal output, and the README expects the user to monitor and abort when needed.
Privacy notes: Terminal output can expose secrets, API keys, tokens, environment variables, shell history, prompts, hostnames, usernames, file paths, git remotes, logs, stack traces, credentials, and local project data., Commands typed by Claude may be stored in shell history, terminal scrollback, logs, audit systems, or process histories., Reading the active session buffer may reveal unrelated work already visible in iTerm2., Do not use this server in terminals connected to production systems, customer data, privileged shells, or secret-bearing sessions unless that exposure is approved.
Author: Ferris Lucas
Submitted by: oktofeesh1
Claim status: unclaimed
Last verified: 2026-06-06

Decision playbook

Review trust signals before you adopt

Signals are present but mixed. Use the checklist below to confirm the source and operational safety for your environment.

Compare context

Selected

Current score

Baseline

—

Delta

No baseline selected

No major trust-signal divergence detected in the current selection.

Source and provenance checks

Needs review

Confirm ownership and provenance before trusting install instructions.

Source link availableRequired
Open the canonical repository and verify ownership.
Done
Source provenance statusRequired
Marked as source-backed.
Done
Metadata reviewed
No reviewed flag detected in metadata.
Pending

Safety and privacy checks

Complete

Validate risk disclosures before installation or API wiring.

Safety notes presentRequired
Review the listed safety guidance before running commands.
Done
Privacy notes presentRequired
Review data handling notes before connecting accounts or secrets.
Done
Trust level risk gateRequired
Trust level does not block evaluation.
Done

Package and install checks

Needs review

Check package metadata and artifact integrity signals.

Install payload available
Install or copy payload is available for review.
Done
Package verification flag
No package verification flag provided.
Pending
Checksum metadata
No checksum provided for downloaded artifact.
Pending

Compare-driven decision checks

Needs review

Use compare context to validate trade-offs before adoption.

Compare tray has multiple entries
Add at least one more entry to compare trust differences.
Pending
Baseline comparison available
No baseline peer selected yet.
Pending
Diverging trust signals identified
No major trust-signal divergence found.
Pending

Setup at a glance

CLI install

Copy-ready — paste the snippet to get started.

5 minutes

Install command

Provided

Config snippet

Provided

Copy snippet

Provided

Prerequisites

5 to clear

Platforms

4 listed

Install type

CLI install

Adoption plan

Balanced adoption plan

Current risk score 24/100. Use staged verification before broader rollout.

Risk 24

Pre-adoption checks

Validate source and review signals before any execution.

Confirm source provenanceRequired
Source URL/provenance metadata is present.
Done
Confirm metadata review state
No review metadata found; increase manual validation.
Pending
Verify install payload
Install/config payload exists and can be inspected.
Done

Security checks

Confirm safety, privacy, and package integrity signals.

Review safety notesRequired
Safety notes are present.
Done
Review privacy notesRequired
Privacy notes are present.
Done
Verify package integrity metadata
No package verification/checksum metadata.
Pending

Rollout

Adopt in controlled steps based on the selected plan.

Run in isolated sandbox firstRequired
Use a constrained sandbox and observe behavior across multiple tasks.
Pending
Roll out graduallyRequired
Roll out to a small cohort before wider usage.
Pending
Set monitoring and fallback
Define rollback path and monitor errors after adoption.
Pending

Evidence readiness

Evidence readiness matrix · balanced

Missing required evidence: Metadata review. Risk score 31.

Risk 31

Source provenance

Present

Source repository/provenance is listed.

Required in this preset

Metadata review

Missing

Review metadata is missing.

Required in this preset

Safety notes

Present

Safety notes are present.

Required in this preset

Privacy notes

Present

Privacy notes are present.

Optional in this preset

Package integrity

Missing

Package integrity metadata is missing.

Optional in this preset

Install payload

Present

Install payload is available.

Required in this preset

Required gaps: Metadata review

Decision timeline

Decision timeline · balanced

Blocking gaps: Check metadata review status. Risk 28.

Risk 28

triage

Confirm source provenanceRequired

Source/provenance metadata is available.

Done

triage

Check metadata review statusRequired

Review metadata is missing.

Pending

verify

Review safety notesRequired

Safety notes are available.

Done

verify

Review privacy notes

Privacy notes are available.

Done

verify

Validate package integrity metadata

Package integrity metadata is missing.

Pending

rollout

Verify install payload and commandsRequired

Install payload is available.

Done

Blockers: Check metadata review status

Prerequisite readiness

5 prerequisites to line up before setup. Includes a review or approval gate.

0/5 ready

Install & runtime1Review & approval1General35 minutes

Safety & privacy surface

6 safety and 4 privacy notes across 3 risk areas. Review closely: credentials & tokens, network access.

3 areas

SafetyCredentials & tokensiTerm MCP gives Claude direct access to the active iTerm2 terminal session.
SafetyExecution & processesThe README states that the server has no built-in command safety restrictions and does not evaluate command risk.
SafetyNetwork accessThe write_to_terminal tool can run shell commands, paste multiline input, interact with REPLs, trigger builds, modify files, start network tools, or run destructive commands.
SafetyExecution & processesThe send_control_character tool can send Control-C, Control-Z, Escape, telnet escape, and other control characters that interrupt or alter running processes.
SafetyCredentials & tokensThe source uses AppleScript through osascript to write text to iTerm2, read the active session buffer, retrieve the TTY, and send control characters.
SafetyExecution & processesThe model may not know whether a command succeeded until it reads terminal output, and the README expects the user to monitor and abort when needed.
PrivacyCredentials & tokensTerminal output can expose secrets, API keys, tokens, environment variables, shell history, prompts, hostnames, usernames, file paths, git remotes, logs, stack traces, credentials, and local project data.
PrivacyExecution & processesCommands typed by Claude may be stored in shell history, terminal scrollback, logs, audit systems, or process histories.
PrivacyCredentials & tokensReading the active session buffer may reveal unrelated work already visible in iTerm2.
PrivacyCredentials & tokensDo not use this server in terminals connected to production systems, customer data, privileged shells, or secret-bearing sessions unless that exposure is approved.

Safety notes

iTerm MCP gives Claude direct access to the active iTerm2 terminal session.
The README states that the server has no built-in command safety restrictions and does not evaluate command risk.
The write_to_terminal tool can run shell commands, paste multiline input, interact with REPLs, trigger builds, modify files, start network tools, or run destructive commands.
The send_control_character tool can send Control-C, Control-Z, Escape, telnet escape, and other control characters that interrupt or alter running processes.
The source uses AppleScript through osascript to write text to iTerm2, read the active session buffer, retrieve the TTY, and send control characters.
The model may not know whether a command succeeded until it reads terminal output, and the README expects the user to monitor and abort when needed.

Privacy notes

Terminal output can expose secrets, API keys, tokens, environment variables, shell history, prompts, hostnames, usernames, file paths, git remotes, logs, stack traces, credentials, and local project data.
Commands typed by Claude may be stored in shell history, terminal scrollback, logs, audit systems, or process histories.
Reading the active session buffer may reveal unrelated work already visible in iTerm2.
Do not use this server in terminals connected to production systems, customer data, privileged shells, or secret-bearing sessions unless that exposure is approved.

Prerequisites

macOS with iTerm2 running.
Node.js 18 or newer available to the MCP client runtime.
macOS Automation and accessibility permissions reviewed for controlling iTerm2.
Active iTerm2 tab selected intentionally before allowing Claude to use the server.
Human supervision and an abort plan for multi-step terminal tasks.

Schema details

Install type: cli
Troubleshooting: No

Source repository stats

Scope: Source repo

Collection metadata

Estimated setup: 5 minutes
Difficulty: advanced

Full copyable content

{
  "mcpServers": {
    "iterm-mcp": {
      "command": "npx",
      "args": ["-y", "iterm-mcp"]
    }
  }
}

About this resource

Content

iTerm MCP is a local Model Context Protocol server that connects Claude to the active iTerm2 terminal session. It lets the model write text into the terminal, read a requested number of output lines, and send control characters such as Control-C or Escape.

The server is designed for supervised local terminal assistance, REPL workflows, and CLI sessions where the user wants to watch what Claude is doing. It is not a sandbox and does not include command safety restrictions.

Source Review

These sources were reviewed on 2026-06-06. Prefer the live repository, README, npm registry metadata, package metadata, source implementation, terminal executor, output reader, control-character sender, and license for current installation steps, tool behavior, terminal control details, and safety notes.

Features

npm package iterm-mcp.
Stdio MCP server launched with npx -y iterm-mcp.
write_to_terminal tool for writing text to the active iTerm2 session.
read_terminal_output tool for reading a requested number of terminal output lines.
send_control_character tool for sending terminal control characters.
AppleScript integration through osascript.
Active iTerm2 session and TTY detection.
Support for REPL and interactive CLI workflows.
MIT license.

Installation

Configure an MCP client on macOS with iTerm2 running:

{
  "mcpServers": {
    "iterm-mcp": {
      "command": "npx",
      "args": ["-y", "iterm-mcp"]
    }
  }
}

Before using the server, select the intended iTerm2 tab and keep the terminal visible. Start with small, reversible commands until the workflow is trusted.

Use Cases

Ask Claude to inspect the last few lines of a long-running command.
Let Claude help inside a supervised REPL session.
Run small CLI commands while watching the active terminal.
Send Control-C to interrupt a command after human approval.
Debug command output without copying terminal text into chat manually.
Pair with a developer who wants model help in the same shell session they are watching.

Safety and Privacy

iTerm MCP is effectively local terminal control. It can type commands into the active shell, interact with REPLs, interrupt processes, and read terminal scrollback. Use it only when you can supervise the active tab and stop the model if it goes off course.

Avoid using it in privileged shells, production SSH sessions, terminals with secrets in scrollback, or workspaces where accidental commands could damage data. Review commands before execution, and keep destructive operations outside model control unless a human explicitly approves the exact action.

Duplicate Check

Existing content mentions iTerm2 incidentally in a terminal setup guide, but no iTerm MCP, ferrislucas/iterm-mcp, iterm-mcp, or matching source URL entry was found in content/mcp.

#terminal #iterm2 #shell #local-mcp #developer-tools

Source citations

Source methodology →

Add this badge to your README

Show that iTerm MCP is listed on HeyClaude. Paste this Markdown into your README — it renders the badge and links back to this page.

[![Listed on HeyClaude](https://heyclau.de/badge/mcp/iterm-mcp.svg)](https://heyclau.de/entry/mcp/iterm-mcp)

How it compares

iTerm MCP side by side with 3 alternatives on trust, install, platform support, and disclosed safety notes — all from reviewed registry metadata.

Field	iTerm MCP MCP server that gives Claude access to the active iTerm2 session for writing terminal input, reading terminal output, and sending control characters. Open dossier	Agent Device MCP Server Official MCP server for agent-device, Callstack's device automation CLI for inspecting, controlling, debugging, recording, and collecting evidence from iOS, Android, TV, macOS, Linux, React Native, Expo, Flutter, and native apps. Open dossier	Agentset MCP Server Official Agentset MCP server that lets Claude retrieve cited knowledge-base results from an Agentset namespace through the `knowledge-base-retrieve` tool, with optional tenant scoping and custom tool descriptions. Open dossier	Bright Data Web MCP Server MCP server that connects Claude to Bright Data web search, scraping, browser automation, public web datasets, and package metadata tools. Open dossier
Next steps	Open dossier API JSON Open LLM MCP feed Open source Newsletter Claim listing	Open dossier API JSON Open LLM MCP feed Open source Newsletter Claim listing	Open dossier API JSON Open LLM MCP feed Open source Newsletter Claim listing	Open dossier API JSON Open LLM MCP feed Open source Newsletter Claim listing
Trust
Review status	Not reviewed	Not reviewed	Not reviewed	Not reviewed
Package trust	Package not verified	Package not verified	Package not verified	Package not verified
Source provenance	Source-backed	Source-backed	Source-backed	Source-backed
Submitter	oktofeesh1	oktofeesh1	oktofeesh1	oktofeesh1
Install risk	Review first	Review first	Review first	Review first
Notes	Safety ✓ Privacy ✓	Safety ✓ Privacy ✓	Safety ✓ Privacy ✓	Safety ✓ Privacy ✓
Brand	—	agent-device	Agentset	Bright Data
Category	mcp	mcp	mcp	mcp
Source	Source-backed	Source-backed	Source-backed	Source-backed
Author	Ferris Lucas	Callstack	Agentset	Bright Data
Added	2026-06-06	2026-06-06	2026-06-06	2026-06-05
Platforms	Claude Code Codex Cursor Claude Desktop	Claude Code Claude Desktop	Claude Code Claude Desktop	Claude Code Claude Desktop
Harness	Claude Code Codex Cursor Claude Desktop	Claude Code Claude Desktop	Claude Code Claude Desktop	Claude Code Claude Desktop
Source repo	—	—	—	—
Safety notes	✓iTerm MCP gives Claude direct access to the active iTerm2 terminal session. The README states that the server has no built-in command safety restrictions and does not evaluate command risk. The write_to_terminal tool can run shell commands, paste multiline input, interact with REPLs, trigger builds, modify files, start network tools, or run destructive commands. The send_control_character tool can send Control-C, Control-Z, Escape, telnet escape, and other control characters that interrupt or alter running processes. The source uses AppleScript through osascript to write text to iTerm2, read the active session buffer, retrieve the TTY, and send control characters. The model may not know whether a command succeeded until it reads terminal output, and the README expects the user to monitor and abort when needed.	✓Agent Device MCP exposes structured tools backed by `AgentDeviceClient`; the docs state it does not expose generic shell execution over MCP. Tools and CLI workflows can open apps, inspect UI, tap, type, scroll, perform gestures, wait, assert state, handle alerts, and close sessions. Evidence workflows can capture screenshots, recordings, logs, traces, network traffic, performance samples, crash context, React profiles, and replay files. Mutating commands should run serially against one session, and separate sessions or devices should be used for parallel work. Prefer dedicated test devices or simulators, and require approval before entering credentials, submitting forms, changing settings, installing apps, sending messages, or touching production accounts.	✓The MCP server sends Claude's retrieval queries to the Agentset API using the configured API key and namespace. The `knowledge-base-retrieve` tool can return up to 100 results per call and can rerank results by relevance. Namespace and tenant selection control which indexed documents are searchable; review them before connecting a shared agent. API keys should be scoped, rotated, and stored only in the MCP server environment or a secret manager. Custom tool descriptions can influence when the model calls the retrieval tool, so review them before use in production workflows.	✓This server sends web searches, URLs, scraping targets, browser actions, package names, and dataset requests to Bright Data APIs. Review website terms, robots policies, rate limits, jurisdictional requirements, and internal scraping policies before automating collection. `PRO_MODE`, browser automation groups, data-product groups, and batch tools can increase cost, request volume, and operational impact. The server can create or use Bright Data zones through API calls; review account permissions and zone settings before running it with broad API tokens. Use `RATE_LIMIT`, group selection, and explicit tool allowlists to keep agent-driven browsing and scraping bounded.
Privacy notes	✓Terminal output can expose secrets, API keys, tokens, environment variables, shell history, prompts, hostnames, usernames, file paths, git remotes, logs, stack traces, credentials, and local project data. Commands typed by Claude may be stored in shell history, terminal scrollback, logs, audit systems, or process histories. Reading the active session buffer may reveal unrelated work already visible in iTerm2. Do not use this server in terminals connected to production systems, customer data, privileged shells, or secret-bearing sessions unless that exposure is approved.	✓Screenshots, recordings, traces, logs, network dumps, replay files, reports, UI snapshots, typed input, and React profiles can contain private UI state, tokens, request data, customer information, or credentials. macOS, iOS, Android, and TV automation can expose local app state, notifications, device names, package identifiers, app content, system dialogs, and permission prompts. Network inspection artifacts may include headers, payloads, session identifiers, URLs, and API data; review before sharing or committing. Interactive CLI runs may check npm for newer package versions unless `AGENT_DEVICE_NO_UPDATE_NOTIFIER=1` is set.	✓Retrieved chunks can include private documents, product specs, policies, support content, internal procedures, historical project information, or customer-specific data. Retrieval queries, namespace IDs, tenant IDs, document chunks, citations, and tool outputs may be visible to the MCP client, model provider, Agentset logs, and application telemetry. Tenant IDs are useful for data segregation, but incorrect tenant or namespace configuration can expose the wrong knowledge base. Do not paste API keys, namespace IDs, tenant IDs, or retrieved private chunks into shared issue reports, screenshots, or repository files.	✓Bright Data API tokens must stay in environment variables or secret managers and should never be committed to MCP configuration files. Queries, URLs, package names, web pages, scraping outputs, dataset filters, and browser activity may be visible to Bright Data, the MCP client, and the model provider. Public web data can still contain personal data, copyrighted content, customer information, or contractual restrictions. Tool outputs can include scraped page text, search results, social or ecommerce dataset fields, package metadata, and browser screenshots depending on enabled tools.
Prerequisites	macOS with iTerm2 running. Node.js 18 or newer available to the MCP client runtime. macOS Automation and accessibility permissions reviewed for controlling iTerm2. Active iTerm2 tab selected intentionally before allowing Claude to use the server.	Node.js 22 or newer and `agent-device` installed globally or project-locally. Xcode tooling for iOS, tvOS, or macOS targets, or Android SDK and ADB for Android targets. Device, simulator, emulator, TV, macOS, or Linux desktop target that the agent is allowed to automate. Required local permissions such as Android device trust, iOS Developer Mode, macOS Accessibility, and Screen Recording where applicable.	Agentset account or self-hosted Agentset deployment with a populated namespace. Agentset API key with access to the namespace Claude should query. Node.js 18.17 or newer for running the `@agentset/mcp` package. Namespace ID selected with `--ns` or `AGENTSET_NAMESPACE_ID`.	Node.js and npx available to the MCP client runtime. Bright Data account and API token stored as `API_TOKEN`. Review of Bright Data plan limits, free-tier scope, paid modes, and data-product terms. A decision about whether to use default rapid tools, `PRO_MODE`, `GROUPS`, or explicit `TOOLS`.
Install	`npx -y iterm-mcp`	`claude mcp add --transport stdio --scope user agent-device -- agent-device mcp`	Run `npx @agentset/mcp --ns <namespace-id>` with `AGENTSET_API_KEY` set in the MCP server environment.	`npx @brightdata/mcp`
Config	`{ "mcpServers": { "iterm-mcp": { "command": "npx", "args": ["-y", "iterm-mcp"] } } }`	`{ "mcpServers": { "agent-device": { "command": "agent-device", "args": ["mcp"] } } }`	`{ "mcpServers": { "agentset": { "command": "npx", "args": ["-y", "@agentset/mcp@latest", "--ns", "ns_xxx"], "env": { "AGENTSET_API_KEY": "agentset_xxx" } } } }`	`{ "mcpServers": { "bright-data": { "command": "npx", "args": ["@brightdata/mcp"], "env": { "API_TOKEN": "YOUR_BRIGHT_DATA_API_TOKEN", "GROUPS": "code,research", "RATE_LIMIT": "100/1h" } } } }`
Citations	Source repositorygithub.com 2026-07-21T07:17:01+00:00 Documentationgithub.com Submitted by oktofeesh12026-06-06 Source methodology →	Source repositorygithub.com 2026-07-21T07:17:01+00:00 Documentationgithub.com Submitted by oktofeesh12026-06-06 Source methodology →	Source repositorygithub.com 2026-07-21T07:17:01+00:00 Documentationdocs.agentset.ai Submitted by oktofeesh12026-06-06 Source methodology →	Source repositorygithub.com 2026-07-21T07:17:01+00:00 Documentationbrightdata.com Submitted by oktofeesh12026-06-05 Source methodology →
Claim	Unclaimed	Unclaimed	Unclaimed	Unclaimed