macOS / local stdio MCP / MIT

Your agents.
Your terminals.
One conversation.

Give your coding agent access to iTerm2. Launch coding CLIs, read their progress, and send the next instruction from the same conversation.

Get started ↓Read the docs ↗

Workflow / illustration

$ uvx --python 3.12
goals-iterm-mcp@0.2.0 serve

agent → list_sessions
Find the exact session ID.

agent → read_screen
Inspect progress before the next step.

Your conversation MCP-capable agent iTerm2 Coding CLI

A workflow built around your terminals.

See the work in progress

List terminal sessions and read screens or scrollback with explicit session IDs.

Give each project a workspace

Create windows and tabs, name sessions, and send instructions to the intended terminal.

Keep the next step close

Let a supervising agent inspect results, give follow-up instructions, and check completion.

Setup

Connect your Mac.

The MCP server connects an agent to your local terminals. Start with iTerm2, then configure your MCP client.

Complete documentation ↗

Prepare iTerm2
Use macOS and keep iTerm2 running. Enable Settings → General → Magic → Python API. Approve the iTerm2 authorization dialog when prompted.
Check the package
Install uv from its official instructions if needed. The documented package version is 0.2.0 and uses Python 3.12.
```
uvx --python 3.12 goals-iterm-mcp@0.2.0 --help
```
Install uv · PyPI 0.2.0

Configure your MCP client

Use the absolute path returned by command -v uvx. Add the configuration below using your client’s supported format. Preserve unrelated settings.

{
  "mcpServers": {
    "iterm": {
      "command": "/absolute/path/to/uvx",
      "args": [
        "--python",
        "3.12",
        "goals-iterm-mcp@0.2.0",
        "serve"
      ]
    }
  }
}

Check the connection
Reload the MCP connection, discover the tools, and run list_sessions. Authenticate each coding CLI in iTerm2 before starting a task.

The client needs local access to this Mac. A cloud-only chat cannot directly reach iTerm2. Mobile use requires a remote interface connected to an agent with local MCP access.

Example prompt

Start with a clear task.

In a dedicated iTerm2 session, launch my coding CLI in /path/to/project.
Ask it to diagnose the login issue, implement a fix, and run relevant tests.
Read progress before sending follow-up instructions. Verify the final result.

Before you begin.

How is this different from the companion skill?

The MCP server provides terminal tools. goals-iterm-skill adds instructions for task delegation, monitoring, decisions, recovery, and verification.

What access does the server have?

By default it can operate on all iTerm2 sessions owned by the current user. Use --read-only to observe only, or repeat --session-id <ID> to limit access. Session restrictions disable window and tab creation.

Does a successful send mean the command finished?

No. The acknowledgment confirms an iTerm2 API call. The supervising agent still needs to inspect terminal output and verify the result.

Does it include a background task monitor?

No. The server exposes terminal tools. The supervising agent and its host manage monitoring, continuation, and scheduling.

Your agents.Your terminals.One conversation.