poof-mcp

An MCP (Model Context Protocol) server that provides AI agents with real terminal control capabilities on macOS.

Features

• Terminal session management via zmx
• Visible Terminal.app windows - watch the AI work in real-time
• Keystroke control - send individual keys or modifier combinations
• Text typing - fast text input
• Screen text capture - read terminal content as plain text
• Wait helpers - wait for text or screen stability
• Resize & restart - control terminal dimensions and restart sessions

Prerequisites

1. zmx - Terminal session manager

# macOS (Apple Silicon)
curl -LO https://zmx.sh/a/zmx-0.0.2-macos-aarch64.tar.gz
tar -xzf zmx-0.0.2-macos-aarch64.tar.gz
mv zmx ~/.local/bin/

# macOS (Intel)
curl -LO https://zmx.sh/a/zmx-0.0.2-macos-x86_64.tar.gz
tar -xzf zmx-0.0.2-macos-x86_64.tar.gz
mv zmx ~/.local/bin/

2. macOS Permissions

poof-mcp uses AppleScript to control Terminal.app, which requires permissions:

1. Accessibility - Required for keyboard input
2. Automation - Required to control Terminal.app

Note: On first use, you may see macOS permission dialogs. Grant access to the app running the MCP server (e.g., Claude, VS Code, Terminal).

Installation

# Clone the repository
git clone https://github.com/mattapperson/poof-mcp.git
cd poof-mcp

# Install dependencies (including native modules)
bun install

Usage

As an MCP Server

Add to your Claude Code MCP configuration:

claude mcp add poof-mcp -- /path/to/poof-mcp/bin/poof-mcp

Or add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "poof-mcp": {
      "command": "/path/to/poof-mcp/bin/poof-mcp"
    }
  }
}

CLI

./bin/poof-mcp --help     # Show help
./bin/poof-mcp --version  # Show version
./bin/poof-mcp            # Start MCP server (stdio)

MCP Tools

Tool	Description
send_keystrokes	Send key presses (e.g., ["enter"], ["up", "up", "enter"])
type_text	Type a string
get_screen_text	Get screen as plain text
get_status	Get terminal status
list_sessions	List active sessions
kill_session	Kill a session
create_session	Create new zmx session + open Terminal.app
resize_terminal	Resize the terminal
restart_terminal	Restart the terminal (optionally with a new command)
wait_for_text	Wait for text to appear on screen (5s default timeout)
wait_for_stable	Wait for screen to stop changing (500ms stable duration)

Keystroke Examples

The send_keystrokes tool supports:

• Single characters: a, b, 1, etc.
• Special keys: enter, tab, escape, space, backspace
• Arrow keys: up, down, left, right
• Function keys: f1 through f12
• Modifiers: ctrl+c, alt+f, shift+a, cmd+v

Development

# Run in development mode
bun run dev

Architecture

Claude Code (AI Agent)
    ↓ (JSON-RPC over stdio)
MCP Server (TypeScript/Bun)
    ↓
Terminal Manager
    ├── zmx commands (session management)
    └── AppleScript (Terminal.app control)
        ↓
macOS Terminal.app + zmx session

How It Works

1. Session Management: Uses zmx for terminal session persistence
2. Terminal Control: AppleScript controls macOS Terminal.app for keystrokes and text input
3. Text Extraction: AppleScript reads Terminal.app content directly

License

MIT