IT
Code Execution

iTerm MCP Server for In Session Command Execution

Execute commands in your current iTerm session with an MCP server for seamless REPL and CLI assistance.

View on GitHub
Quick Install
npx -y @ferrislucas/iterm-mcp

Overview

This project provides an MCP (Model Context Protocol) server that lets tools and AI agents execute commands directly in your current iTerm session. Instead of opening a separate terminal or copying/pasting commands back and forth, the server exposes a controlled interface that can send shell input to an active iTerm session and stream the resulting output back to the caller. That makes it convenient to build REPL helpers, CLI assistants, and automation workflows that operate on the same terminal context you are actively using.

The server is most useful when you want an assistant (or local automation) to observe and act in the same shell environment — preserving working directory, shell state, and session-specific variables — while still maintaining explicit control and auditing. It is designed to fit into tool-chains that implement MCP or similar protocols for model-assisted command execution.

Features

  • Execute commands in the currently focused iTerm session (preserves session state and cwd)
  • Stream stdout/stderr back to the caller for immediate feedback
  • Authentication support via secret token to limit who can send commands
  • Configurable port and logging for local development and long-running services
  • Simple HTTP-based API suitable for integration with LLM agents, editor plugins, or automation scripts
  • Basic safety controls (e.g., explicit confirmation, allow/deny lists) can be added in front of the server

Installation / Configuration

The repository is available at https://github.com/ferrislucas/iterm-mcp. The exact install steps depend on the project language/runtime; the following is a general pattern you can adapt.

Clone the project:

git clone https://github.com/ferrislucas/iterm-mcp.git
cd iterm-mcp

If the project requires a language runtime (Python / Node / Go / etc.), follow its README to install dependencies. Example for a Python-based server:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Set configuration via environment variables or CLI flags. Common options:

export MCP_PORT=8080
export MCP_SECRET="change-me"
export MCP_LOG_LEVEL=info

Start the server (example CLI form — adapt as needed to the project’s actual command):

# Generic start command; replace with the project's start command
python -m iterm_mcp.server --port $MCP_PORT --secret "$MCP_SECRET"

Run as a background service (systemd example):

# /etc/systemd/system/iterm-mcp.service
[Unit]
Description=iTerm MCP Server
After=network.target

[Service]
User=youruser
WorkingDirectory=/home/youruser/iterm-mcp
ExecStart=/home/youruser/iterm-mcp/venv/bin/python -m iterm_mcp.server --port 8080 --secret "change-me"
Restart=on-failure

[Install]
WantedBy=multi-user.target

Then enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now iterm-mcp

Security notes:

  • Keep MCP_SECRET secret and use a strong value when exposing the server to networks.
  • Run behind a reverse proxy or firewall when needed.
  • Consider adding allowlists or human-confirmation steps for sensitive commands.

Available Resources

  • GitHub repository: https://github.com/ferrislucas/iterm-mcp
  • Example client integrations: use simple HTTP clients (curl, fetch) or adapt an LLM agent connector that speaks MCP-style actions.
  • Logging and debugging: configure LOG_LEVEL to debug for troubleshooting startup and command flows.

Example basic HTTP request (pseudo-API — adapt to the server’s documented endpoints):

curl -X POST "http://localhost:8080/execute" \
  -H "Authorization: Bearer $MCP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"command": "pwd && ls -la", "session": "current"}'

Expected behavior:

  • The server sends the command to the currently focused iTerm session.
  • The output is captured and returned in the HTTP response or streamed via a websocket.

Use Cases

  • REPL assistance: Let an LLM act as a REPL helper that can run code snippets, inspect variables, or run tests in the same shell session without manual copy/paste.

    • Example: Ask the assistant to run pytest tests/test_models.py::TestModel::test_save and return failing tracebacks.

  • CLI-based developer workflows: Automate repetitive shell tasks while keeping local context (virtualenvs, environment variables).

    • Example: From a local editor plugin, send build, lint, and run commands to the active iTerm tab and surface output inline.

  • Debugging and exploration: When investigating a bug interactively, have a tooling agent run diagnostic commands (netstat, ps, tail logs) in the same session to preserve expected shell state.

    • Example: tail -n 200 /var/log/myapp.log | grep ERROR

  • Pair programming / teaching: A mentor or automated tutor can demonstrate commands in your terminal session while you watch or try variations, using the same session state.

Tips and Troubleshooting

  • If commands don’t appear in the expected session, verify that iTerm is focused and that the server has permission to control the terminal (macOS may require accessibility permissions).
  • Use verbose logging during setup to ensure the server can discover and target the correct iTerm session.
  • For complex or long-running output, prefer streaming endpoints (websockets or chunked responses) to avoid timeouts.

If you need advanced integrations (agent orchestration, per-command confirmation UIs, or a web-based dashboard), build a lightweight proxy in front of the server to implement those policies while keeping the core server focused on reliable session execution.

Tags:code-execution