Skip to main content
Glama
GrigoriLab

claude-mux-iterm

by GrigoriLab
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

claude-mux-iterm

MCP server enabling communication between Claude Code sessions in iTerm2 panes.

Primary use case: Notify other sessions when PR is merged to main so they can pull latest changes.

Installation

pip install claude-mux-iterm

Or with uv:

uv pip install claude-mux-iterm

Related MCP server: mcp-terminal-share

Configuration

Add to your Claude Code MCP settings (~/.claude/settings.json or project-level):

{
  "mcpServers": {
    "claude-mux-iterm": {
      "command": "uvx",
      "args": ["claude-mux-iterm"]
    }
  }
}

Or if installed with pip:

{
  "mcpServers": {
    "claude-mux-iterm": {
      "command": "claude-mux-iterm"
    }
  }
}

Tools

register_session(task_id)

Register the current iTerm2 session with a task ID. This allows other sessions to find and communicate with this session.

register_session("task-a")

list_sessions()

List all registered active sessions.

list_sessions()

send_message(target_task_id, content, source_task_id)

Send a message to a specific session.

send_message("task-b", "PR merged to main, please pull latest", "task-a")

broadcast_message(content, source_task_id)

Send a message to all other active sessions.

broadcast_message("PR #123 merged to main, please pull latest", "task-a")

list_messages(current_task_id, unread_only)

List messages received by this session.

list_messages("task-a", unread_only=True)

acknowledge_message(message_id, current_task_id)

Mark a message as read/acknowledged.

acknowledge_message("msg_abc123", "task-a")

Usage Example

Pane 1 (working on feature branch):

# Register this session
register_session("feature-auth")

# Check for messages periodically
list_messages("feature-auth", unread_only=True)

Pane 2 (just merged a PR):

# Register this session
register_session("main-work")

# Notify all other sessions about the merge
broadcast_message("PR #42 merged to main with auth changes - please pull latest", "main-work")

Message Format

Messages are injected into sessions using a wire format:

[CLAUDE-MUX-ITERM-MESSAGE]{"message_id":"msg_abc123",...}[/CLAUDE-MUX-ITERM-MESSAGE]

Claude Code sessions can parse this format to extract the message content.

Storage

Session registrations and messages are stored in:

~/.claude-mux-iterm/
├── sessions/
│   └── {task_id}.json           # Session registrations
└── messages/
    └── {task_id}/
        ├── inbox/               # Received messages
        ├── outbox/              # Sent messages
        └── delivered/           # Acknowledged messages

Requirements

  • macOS (uses iTerm2 AppleScript)

  • iTerm2 running

  • Python 3.10+

Development

# Clone the repo
git clone https://github.com/GrigoriLab/claude-mux-iterm
cd claude-mux-iterm

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Run type checking
uv run mypy src

# Run linting
uv run ruff check src tests

License

MIT License - see LICENSE file.

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/GrigoriLab/claude-mux-iterm'

If you have feedback or need assistance with the MCP directory API, please join our Discord server