Ghost OS MCP
A Swift MCP server for macOS: an agent sees any app through the accessibility tree, clicks and types, and saves repeatable workflows as JSON recipes
- 1,681 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Controls any Mac app in your name: presses buttons, types text, sends emails and messages
- Learning mode reads the keyboard and mouse through a system event tap and stores your actions with the contents of elements
- The wizard writes a permission for all its tools into Claude Code settings, which switches off confirmations
Install
- Works in
Manual install
brew install ghostwright/ghost-os/ghost-osInstalls the `ghost` command. Needs Homebrew and macOS 14 or newer.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Controls any Mac app in your name: presses buttons, types text, sends emails and messages
- Learning mode reads the keyboard and mouse through a system event tap and stores your actions with the contents of elements
- The wizard writes a permission for all its tools into Claude Code settings, which switches off confirmations
This is third-party code. Review the repository files before installing.
What it does
Ghost OS is a Swift MCP server that lets an agent control apps on a Mac. It installs through Homebrew, and `ghost setup` grants permissions, registers the server in Claude Code, copies the recipes and prepares the vision model. According to the author the server gives the agent 29 tools: inspection, clicks, typing, scrolling, dragging, window control and waiting for conditions. The agent reads the interface through the macOS accessibility tree, getting names, roles and positions of elements. When the tree falls short, for example in web apps such as Gmail or Slack, the `ghost_ground` and `ghost_parse_screen` tools turn to the local ShowUI-2B model. It runs in a Python helper on `localhost:9876` that starts on demand. Screenshots are not needed for the main work and stay a separate tool for debugging. A familiar workflow can be saved as a recipe. A recipe is a JSON file with steps, parameters and wait conditions in `~/.ghost-os/recipes`. The `ghost_run` tool executes it with parameter substitution, and the repository ships four ready ones: sending an email in Gmail, a message in Slack, a folder in Finder and downloading a paper from arXiv. Learning mode `ghost_learn_start` watches you perform a task by hand, and after `ghost_learn_stop` the agent turns it into a new recipe. `ghost doctor` runs diagnostics.
Who it is for. For Mac owners working with Claude Code, Cursor or another MCP client who want an agent to act in ordinary apps that have no API.
Good fit when
- You want the agent to send an email in Gmail or a message in Slack by filling in fields in a browser or app window
- The same action repeats every day, and you want to record it once as a recipe and run it later with different parameters
- A web app exposes elements poorly through the accessibility tree and you need the local model to find a button by its picture
- You want to read every step before running: recipes are plain JSON files
Not a fit when
- You run Windows or Linux: Ghost OS works only on macOS 14 and newer
- Disk space is tight or Python will not install: the ShowUI-2B model takes about 3 GB, and `ghost setup` downloads it and installs the packages
- You need a tool without access to keyboard and mouse input: learning mode asks for the Input Monitoring permission and watches your actions
- You only want to automate web pages: dedicated servers exist for the browser, for example Playwright MCP
Example request
Open the Documents folder in Finder, create a folder called October reports there and then tell me what you see in itMCP
- Transport
- stdio
- Authentication
- not required
Limitations
- It needs macOS 14 or newer, the Accessibility and Screen Recording permissions, and for learning mode also Input Monitoring. Building from source requires Swift 6.2.
- The latest release 2.2.1 came out in March 2026. The author notes that finding fields in deep web apps can take about 11 seconds.
- A recipe depends on the interface: gmail-send is built for Gmail in Chrome with the right account, and when the site's markup changes the steps need fixing.
- Setup registers the server in `~/.claude.json` and allows all `mcp__ghost-os__*` tools in `~/.claude/settings.json`, so Claude Code stops asking for confirmation on every action.
- License MIT. You are responsible for what the agent does in your name in email and messengers.
How to disable. Remove the `ghost-os` entry from `mcpServers` in `~/.claude.json` and the `mcp__ghost-os__*` line from `allowedTools` in `~/.claude/settings.json`. Then run `brew uninstall ghost-os`. Recipes, the model and the Python environment live in `~/.ghost-os`, and the whole folder can be deleted.
FAQ
What does the ghost setup command do?
It checks macOS permissions step by step, registers the MCP server in Claude Code, copies the recipes from the repository into `~/.ghost-os/recipes`, creates a Python environment and downloads the ShowUI-2B model. If a step fails, the wizard prints commands for a manual install.
Does Ghost OS send my data to the cloud?
The server itself runs on your Mac, and the vision model starts locally in a helper on `localhost:9876`. The author stresses that data stays on the computer. Only what you ask apps to do leaves it, such as an email sent through Gmail, along with whatever your agent forwards to its language model.
How do I teach Ghost OS a new workflow?
Tell the agent to record the task. It calls `ghost_learn_start`, you perform the actions by hand, and `ghost_learn_stop` returns a sequence of steps with element context. The agent turns it into a recipe with parameters and saves it through `ghost_recipe_save`.
Which ready recipes does the repository have?
Four: `gmail-send` sends an email in Chrome with recipient, subject and body parameters, `slack-send` posts a Slack message, `finder-create-folder` creates a folder, and `arxiv-download` finds a paper on arXiv and downloads it to the desktop.
Why does it need the ShowUI-2B model?
It finds element coordinates from a picture of the window when the accessibility tree does not show them, as happens in web apps. The `ghost_ground` and `ghost_parse_screen` tools reach it through the Python helper. For ordinary apps the tree is enough.
How do I check that the installation went well?
`ghost doctor` lists permissions, processes, the MCP setup, the recipe count, tree readability in running apps and the model. Every line should be marked `ok`.
Discussion
No questions or reviews yet.
Related
MCP serversA Swift MCP server that lets an agent drive any macOS app: click, type and read the interface tree
A macOS CLI and MCP server: screenshots, accessibility-based UI inspection and app control via clicks and typing
MCP server for AppleScript: the agent runs scripts and controls Mac apps, from Notes and Calendar to files
An MCP server for macOS: the agent moves the mouse, types, manages windows and captures the screen when an app has no API
A Rust CLI for macOS: an agent reads any app's interface through the accessibility tree and clicks, types and scrolls by element refs, with no screenshots
Open Computer Use
open-computer-use
An open MCP server for desktop control: the agent reads app state and clicks, types and scrolls on macOS, Linux and Windows
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Ghost OS (this entry) | no | not required | 1,681 | |
| Open Computer Use | no | not required | 2,756 | an open MCP server for desktop control on macOS, Linux and Windows |
| Windows-MCP | no | not required | 10,682 | an MCP server for controlling Windows, works with files and PowerShell |
README in short
The repository holds the Swift server sources split into modules (perception, actions, recipes, learning, vision, MCP), the setup wizard and diagnostics, a Python helper for the vision model, four recipes, the GHOST-MCP.md reference for the agent and work notes. The front page opens with an overview of the new version and a comparison with other tools, followed by installation, the tool list and an architecture diagram.