Poof

Poof MCP Server lets AI agents control macOS Terminal.app in real time. It exposes terminal sessions you can observe and interact with, including keystroke control, fast typing, and screen content capture, enabling powerful automation and testing workflows.

How to use

You run the Poof MCP Server locally and connect an MCP client to drive macOS Terminal sessions. Start a session, view the Terminal.app window in real time, and send keyboard input or text to automate commands. You can resize the terminal, restart sessions, and wait for specific text or screen stability before proceeding. Use the available tools to create, manage, and interrogate terminal sessions, then retrieve rendered screen content as plain text for verification.

How to install

Prerequisites ensure you can build and run the MCP server and interact with Terminal.app.

# 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 and Automation

# When running for the first time, grant access to the MCP server process (e.g., Claude, VS Code, Terminal).

# 3) Install Poof MCP
# Clone repository and install dependencies
git clone https://github.com/mattapperson/poof-mcp.git
cd poof-mcp

# Install dependencies (including native modules)
bun install

# 4) Start the MCP server locally (example)
./bin/poof-mcp

# 5) Optional: run help or version to verify
./bin/poof-mcp --help
./bin/poof-mcp --version

Additional configuration and notes

To use the server as an MCP target, configure your client to communicate with the local stdio server at the path shown when starting the server. The official command to start the server is the stdio entry ./bin/poof-mcp. You will typically start the server and then connect an MCP client to drive Terminal sessions. If you encounter macOS permission prompts, grant accessibility and automation permissions to the app running the MCP server.

Tool usage summary: you can create a new zmx session, open a Terminal.app window, send keystrokes or text, resize or restart the terminal, wait for specific text, and fetch the screen contents as plain text. This enables automated workflows that require real-time terminal interaction.

Security and troubleshooting notes

Only run the MCP server on trusted devices. MacOS permissions dialogs may appear on first use; ensure you grant required permissions to the MCP server process. If Terminal windows do not appear or you do not see expected keystrokes, verify that zmx is running and that the MCP server has the necessary accessibility and automation permissions.

Available tools

send_keystrokes

Send key presses to the active Terminal session, including single keys, arrow keys, function keys, and modifier combinations.

type_text

Type a string of text into the active Terminal session, simulating user input.

get_screen_text

Capture and return the current Terminal window content as plain text for verification or processing.

get_status

Query the current status of the terminal session, such as active window and session health.

list_sessions

List all active zmx sessions that the MCP server can manage.

kill_session

Terminate a running zmx session and close its Terminal window.

create_session

Create a new zmx session and open a Terminal.app window for interaction.

resize_terminal

Adjust the terminal window dimensions to fit content or client layout.

restart_terminal

Restart the terminal session, optionally with a new command to run.

wait_for_text

Pause execution until specified text appears on the screen, with a default timeout.

wait_for_stable

Pause until the screen content stops changing for a set stable duration.