convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
r6e

MCP Server iTerm2

r6e/mcp-server-iterm2

Integração segura do iTerm2 com agentes para observação e anotação

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que expõe o iTerm2 para agentes observarem e anotarem sessões de forma não-destrutiva. Permite inspecionar e decorar sessões (badge, título, cor de aba, variáveis, notificações) sem alterar o ambiente de trabalho do usuário.

Instalação

$npx convez-ai r6e/mcp-server-iterm2

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
4
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 1 mês
Versão
v0.1.1
Issues abertas
6
Contribuidores
2

Casos de uso

  • Monitorar status de sessões de terminal em tempo real
  • Decorar abas e sessões com metadados contextuais
  • Registrar informações de execução de scripts com badges e títulos

Veredito

Ferramenta bem pensada que integra agentes ao iTerm2 mantendo a segurança do ambiente do usuário. Ideal para automação de terminal e monitoramento sem efeitos colaterais.

README

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

mcp-server-iterm2

CI PyPI Python

A Model Context Protocol (MCP) server that exposes iTerm2 to agents for observation and non-destructive annotation. Agents can inspect sessions and decorate them (badge, title, tab color, user variables, notifications) but cannot inject keystrokes, close or spawn sessions, or otherwise alter the user's working environment.

Install

Configure your MCP client (e.g. Claude Desktop, Claude Code):

{
  "mcpServers": {
    "iterm2": {
      "command": "uvx",
      "args": ["mcp-server-iterm2"]
    }
  }
}

Requires macOS, iTerm2, and uv installed.

First run

On first invocation, iTerm2 prompts you to authorize API access for the script. Approve it. Subsequent runs are silent.

If you previously denied access: iTerm2 → Preferences → General → Magic → enable "Python API" and remove mcp-server-iterm2 from the denial list.

Tools

Read

ToolDescription
list_sessionsTree of windows → tabs → sessions, plus a top-level buried_sessions list.
get_session_infoTitle, working dir, profile, badge, dimensions, TTY
get_screen_contentsVisible buffer + cursor position
get_scrollbackLast N lines (default 200, max 5000)
get_recent_outputOutput since a cursor marker (cursor-based pagination)
get_selectionCurrently-selected text
get_variableRead a variable by fully-qualified name (e.g. session.path, user.badge)
list_profilesAvailable profiles by name and GUID

Write (non-destructive)

ToolDescription
set_badgeSet session badge text
set_titleOverride session title
set_tab_colorTint the tab (RGB 0-255)
set_user_variableSet a user.* session variable
post_notificationPost a macOS notification banner

Every session-targeted tool accepts an optional session_id. If omitted, the server uses $ITERM_SESSION_ID from its environment — which works automatically when the agent runs inside iTerm2.

Notes on rendering

  • Badge: for set_badge to display anything, your iTerm2 profile's badge format must include \(user.badge). Configure in iTerm2 → Profiles → General → Badge.
  • Title: whether a set_title override sticks depends on the profile's "Allow terminal apps to change title" and "Title Components" settings. The server always sets the override; iTerm2 controls the rendering.
  • Tab color: set_tab_color writes the legacy tab color plus both light- and dark-mode variants, so the tint takes effect regardless of the profile's split-color preference.
  • Notifications: routed through macOS via osascript. Make sure Terminal/iTerm2 notifications are allowed in System Settings if banners don't appear.

Excluded by design

For safety, these are not exposed: send_text/keystroke injection, closing or spawning sessions/tabs/windows, splitting panes, focus changes, broadcasting input.

Security model

Installing this server gives any MCP client that uses it broad read access to your iTerm2 sessions (screen contents, scrollback, working directories, variables) and limited write access (badge, title, tab color, user.* variables, macOS notifications). Read tools can capture passwords visible on screen; write tools can spoof titles and notifications. The full threat model and reporting flow live in SECURITY.md.

Development

uv sync
uv run pytest tests/unit       # 122 unit tests
uv run ruff check .            # lint
uv run ruff format --check .   # format check
uv run ty check src            # type check

Integration tests (pytest -m integration) and the smoke script (scripts/smoke.py) require running inside an iTerm2 session. See CONTRIBUTING.md for the full development guide and ARCHITECTURE.md for how the pieces fit together.

API stability

This project follows semantic versioning. The current release is in the 0.x series; expect schema refinements between minor versions as the tool surface settles in response to real-world feedback. Pin to a specific version in production.

From 1.0 onward the following will be part of the stable contract — breaking any of them requires a major bump:

  • Tool names and the set of tools. Names and removal of tools are stable; new tools may be added in minor releases.
  • Tool argument names and types. New optional arguments may be added; existing argument names, types, and required-ness do not change.
  • Top-level response keys and value types. New keys may be added in minor releases; existing keys and their types do not change.
  • Error envelope shape. MCPIterm2Error subclasses surface actionable text via to_error_text; unknown exceptions collapse to Internal error: <ExceptionClass>. Callers may pattern-match on this envelope.

Not part of the stable surface:

  • Internal Python modules (server.py, connection.py, tools/*, errors.py, output_cursor.py) — these are implementation details.
  • Specific cursor payload encoding for get_recent_output. Treat the cursor as opaque; pass back whatever the server returned.
  • iTerm2 SDK and macOS version compatibility windows — these follow upstream and may change in minor releases.

Documentation

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados