README.md
AI agents control the macOS Terminal.app using AppleScript and zmx
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:
f1throughf12 - 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
License
MIT
Tools (11)
send_keystrokesSend key presses (e.g., ["enter"], ["up", "up", "enter"])type_textType a stringget_screen_textGet screen as plain textget_statusGet terminal statuslist_sessionsList active sessionskill_sessionKill a sessioncreate_sessionCreate new zmx session + open Terminal.appresize_terminalResize the terminalrestart_terminalRestart the terminal (optionally with a new command)wait_for_textWait for text to appear on screen (5s default timeout)wait_for_stableWait for screen to stop changing (500ms stable duration)Configuration
claude_desktop_config.json
{
"mcpServers": {
"poof-mcp": {
"command": "/path/to/poof-mcp/bin/poof-mcp"
}
}
}Try it
→Open a new terminal session and list the files in my current directory.
→Type 'git status' into the terminal and tell me what the output is.
→Send the 'ctrl+c' keystroke to stop the running process in the terminal.
→Wait for the text 'Successfully compiled' to appear on the terminal screen.
→Resize the terminal window to 100x40 and then restart it.