Skip to main content
Glama

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

Related MCP server: mcp-interactive-terminal

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for terminal control enabling AI to manage terminal sessions via iTerm2 or tmux, with features like screen reading, keyboard/mouse input, and background execution.
      9
      91 npm
      22
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      MCP server that enables AI to fully control macOS — mouse, keyboard, terminal, screenshots, window management, UI element detection, and provides AI-optimized information reporting.
      36
      21 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that gives AI agents real OS-level control of macOS, enabling them to click real buttons, type real keys, and observe rendered screens just like a human would.
      1
      MIT