convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
phpgao

term2mcp — Controle iTerm2 via IA

phpgao/term2mcp

Automatize seu terminal iTerm2 através de assistentes de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que permite assistentes de IA (Claude, CodeBuddy Code, Continue) controlar sessões do iTerm2 programaticamente. Suporta envio de comandos, leitura de output, gerenciamento de panes, captura de telas e listagem de sessões. Construído em Go sobre a biblioteca term2go.

Instalação

$npx convez-ai phpgao/term2mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
v0.1.2
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automatizar execução de comandos no terminal via prompts em linguagem natural
  • Integrar DevOps workflows com assistentes de IA para deploy e troubleshooting
  • Capturar output de comandos para análise e logging automatizado

Veredito

Ferramenta bem-arquitetada que simplifica automação de terminal em ambientes macOS com iTerm2. Requer configuração inicial mas oferece integração sólida com ecossistema Claude e alternativas de MCP.

README

A tradução para o português deste README ainda está na fila.

term2mcp

MCP (Model Context Protocol) server for iTerm2 — empowered by term2go.

Let AI assistants (CodeBuddy Code, Claude Desktop, Continue, etc.) control your iTerm2 sessions programmatically: list sessions, send commands, read output, split panes, take screenshots, and more.

🌐 Website: https://phpgao.github.io/term2mcp/

Prerequisites

  • macOS
  • iTerm2 with Python API enabled
    • Open iTerm2 → Preferences → General → Magic → check Enable Python API
  • Go 1.23+ (only needed for go install)

Installation

From source (recommended)

go install github.com/phpgao/term2mcp@latest

After installation, the binary term2mcp will be in your $GOPATH/bin (usually ~/go/bin). Make sure it's in your PATH.

From release (future)

Pre-built binaries will be available on the Releases page.

Configuration

Choose your MCP client below and follow the step-by-step setup.

CodeBuddy Code

Step 1 — Find your config file

Open CodeBuddy Code, run:

/config

This opens mcp.json in your editor. The actual file path is:

~/.codebuddy/mcp.json

Step 2 — Add term2mcp

{
  "mcpServers": {
    "term2mcp": {
      "command": "term2mcp",
      "args": []
    }
  }
}

Step 3 — Optional: speed up startup with env vars

{
  "mcpServers": {
    "term2mcp": {
      "command": "term2mcp",
      "args": [],
      "env": {
        "ITERM2_COOKIE": "YOUR_COOKIE_HERE",
        "ITERM2_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

How to get these values? See iTerm2 Credentials below.

Step 4 — Verify

Restart CodeBuddy Code. Run /mcp to list servers. You should see term2mcp with status connected.

In the chat, try: "List my iTerm2 sessions" — it should show your windows and tabs.

Claude Desktop

Step 1 — Find your config file

# Config file location
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

If the file doesn't exist, create it:

touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

Step 2 — Add term2mcp

{
  "mcpServers": {
    "term2mcp": {
      "command": "term2mcp",
      "args": []
    }
  }
}

Step 3 — Restart Claude Desktop

Quit and reopen the app. You should see a hammer icon in the chat input — click it to see available tools.

iTerm2 Credentials

term2mcp auto-detects credentials via AppleScript when iTerm2 is running. This works well but adds ~1-2s latency on first connection.

To eliminate this latency, set environment variables:

export ITERM2_COOKIE="xxx"
export ITERM2_KEY="xxx"

How to get the values:

They are stored in iTerm2's private socket directory. You can extract them with:

# Cookie
defaults read com.googlecode.iterm2 Cookie

# Key (base64 encoded)
ls ~/Library/Application\ Support/iTerm2/private/

Or search your environment when inside iTerm2:

# In an iTerm2 session, run:
echo $ITERM2_COOKIE
echo $ITERM2_KEY

These values change occasionally (especially after iTerm2 restart). If connection fails, the auto-detection fallback will handle it transparently.

Tools

ToolDescriptionParameters
list_sessionsList all iTerm2 windows, tabs, and sessions with IDs—
send_textSend text/commands to a session (use \n for Enter)session_id, text, suppress_broadcast?
get_bufferRead terminal output from a sessionsession_id, lines? (default 50, max 500)
create_tabCreate a new tab (or window) with optional initial commandwindow_id?, profile?, command?
split_paneSplit a session vertically or horizontallysession_id, vertical, before?, profile?
screenshotCapture a window or session as a PNG filetarget (window/session), id, output_path
get_variableGet an iTerm2 session variablesession_id, name
set_variableSet an iTerm2 session variablesession_id, name, value
focusGet the currently focused session/tab/window—
activateFocus and bring a specific session to the frontsession_id
inject_keystrokesInject raw bytes/keystrokes into a sessionsession_id, keys
close_sessionClose an iTerm2 session (pane)session_id, force?
set_nameSet the name of a session (displayed in tab/title)session_id, name
set_badgeSet the badge text overlay on a sessionsession_id, text
get_promptGet last command info (text, dir, exit code, state)session_id
list_profilesList all iTerm2 profile names—

Example Conversations

You: List my iTerm2 sessions
AI: [list_sessions] → Window 0 has tab 0 with session "w0_t0_s0"

You: Run ls -la in that session
AI: [send_text: session="w0_t0_s0", text="ls -la\n"]

You: What's the output?
AI: [get_buffer: session="w0_t0_s0"] → total 32
                                    drwxr-xr-x  5 user  staff  160 ...
                                    -rw-r--r--  1 user  staff  123 main.go

You: Open a new tab and run htop
AI: [create_tab: command="htop"] → New tab created, session: "w0_t1_s0"

You: What was the last command's exit code?
AI: [get_prompt: session="w0_t0_s0"] → state: finished, exit: 0

You: Take a screenshot of the window
AI: [screenshot: target="window", id="...", output="/tmp/screen.png"]

Troubleshooting

"cannot connect to iTerm2"

Make sure:

  1. iTerm2 is running
  2. Python API is enabled (Preferences → General → Magic)

Tool not showing up in MCP client

Check ~/.codebuddy/mcp.json or Claude config for typos. The command must be the exact path to the term2mcp binary (run which term2mcp to check).

Connection is slow on first use

This is normal — AppleScript auth takes ~1-2s. Set ITERM2_COOKIE/ITERM2_KEY env vars in the MCP config (see iTerm2 Credentials) to eliminate this delay.

Development

git clone https://github.com/phpgao/term2mcp.git
cd term2mcp

make build   # Build binary
make test    # Run tests
make run     # Run directly
make install # Install to $GOPATH/bin

License

MIT — see LICENSE file.

Ver o original no GitHub

Bom para

Relacionados