How to add iterm-mcp to Claude Desktop

Give MCP clients access to your iTerm session to run commands, read output, and drive REPLs. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 14, 2026 · 560★ · stdio · no auth

Claude Desktop config for iterm-mcp

npx -y iterm-mcp

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

Setup steps

1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
2Paste the iterm-mcp config below under the top-level "mcpServers" key.
3Fill in any placeholder secrets (API keys, paths) in the snippet.
4Save the file, then fully quit and reopen Claude Desktop.
5Open a chat and confirm iterm-mcp's tools appear under the 🔌 tools menu.

Before you start

iTerm2 must be running
Node version 18 or greater

What iterm-mcp can do in Claude Desktop

write_to_terminal

Writes to the active iTerm terminal, often used to run a command. Returns the number of lines of output produced by the command.

read_terminal_output

Reads the requested number of lines from the active iTerm terminal.

send_control_character

Sends a control character to the active iTerm terminal (e.g. ctrl-c, ctrl-z).

Security

No built-in restrictions: iterm-mcp makes no attempt to evaluate the safety of commands that are executed. The user is responsible for using the tool safely and is expected to monitor activity and abort when appropriate. Models can behave in unexpected ways; for multi-step tasks you may need to interrupt the model if it goes off track.

iterm-mcp + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the iterm-mcp config there under the "mcpServers" key and restart the client.

Is iterm-mcp safe to use with Claude Desktop?

How do I install it for Claude Desktop?

Add the server config to your claude_desktop_config.json (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) using command "npx" with args ["-y", "iterm-mcp"]. You can also install automatically via Smithery: npx -y @smithery/cli install iterm-mcp --client claude.

What are the requirements?

iTerm2 must be running, and you need Node version 18 or greater.

Does it restrict dangerous commands?

No. iterm-mcp makes no attempt to evaluate the safety of commands. The user is responsible for using it safely and should monitor activity and abort when appropriate.

View repo Full iterm-mcp page