How to add iterm-mcp to Windsurf

Give MCP clients access to your iTerm session to run commands, read output, and drive REPLs. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

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

Windsurf config for iterm-mcp

npx -y iterm-mcp

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

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the iterm-mcp config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5iterm-mcp's tools become available to Cascade.

Before you start

iTerm2 must be running
Node version 18 or greater

What iterm-mcp can do in Windsurf

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 + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the iterm-mcp config there under the "mcpServers" key and restart the client.

Is iterm-mcp safe to use with Windsurf?

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