Which integrations are available for this server?

Provides terminal control capabilities on macOS, enabling AI agents to manage Terminal.app sessions, send keystrokes, input text, and capture screen content.

How do I use poof-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@poof-mcp open a new terminal session and run brew update" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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:

Accessibility - Required for keyboard input
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

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