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