macOS-MCP — Claude Code MCP server: macOS automation
An MCP server that lets an agent drive macOS: launch apps, click UI elements, capture the desktop state.
claude mcp add macos-mcp -- uvx macos-mcpWhat macOS-MCP does
macOS-MCP bridges an AI agent and the macOS desktop through the Accessibility API. The agent opens applications, moves windows, simulates keyboard and mouse input, pulls interactive elements from the accessibility tree, and runs AppleScript. The Snapshot tool captures screenshots through Screen Recording. No computer vision needed, because the server hands the agent interface structure rather than pixels.
Run it straight away with uvx macos-mcp over stdio, or switch to the sse or streamable-http transport bound to localhost and a port. The macos-mcp install command writes a Launch Agent to ~/Library/LaunchAgents/com.macos-mcp.server.plist so the server starts at every login; logs go to ~/.macos-mcp/. Both HTTP transports expose the server to the network, not just the local machine.
You need Python 3.11 or later, UV, and macOS 12+. Without Accessibility and Screen Recording granted in System Settings the tools will refuse to work: grant both to your terminal, Python and UV, then restart the terminal. If a UV-managed interpreter stays greyed out in the picker, just start the server — it calls AXIsProcessTrustedWithOptions on startup and macOS shows its own consent dialog.
What it helps with
- open an app and focus the right window from the agent
- list clickable elements of a window instead of parsing a screenshot
- run an AppleScript the agent asks for mid-chat
- keep the automation server running at every login
Example prompts for the agent
- Open Finder and go to
~/Projects, then show me what's inside - Take a snapshot of the screen and tell me which window is active
- Run an AppleScript that closes all Safari windows
How to install macOS-MCP
Platform CLI
claude mcp add macos-mcp -- uvx macos-mcpuvx runs the command named after the package; if the README names another one, use uvx --from macos-mcp <command>
Platform CLI
codex mcp add macos-mcp -- uvx macos-mcpuvx runs the command named after the package; if the README names another one, use uvx --from macos-mcp <command>
Config file
{
"mcpServers": {
"macos-mcp": {
"command": "uvx",
"args": [
"macos-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from macos-mcp <command>
Config file
{
"servers": {
"macos-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"macos-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from macos-mcp <command>
Platform CLI
gemini mcp add macos-mcp uvx macos-mcpuvx runs the command named after the package; if the README names another one, use uvx --from macos-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about macOS-MCP
How do I install macOS-MCP in Claude Code?
Run claude mcp add macos-mcp -- uvx macos-mcp. Install UV and Python 3.11+ first, then grant Accessibility and Screen Recording.
What does macOS-MCP do?
It gives an agent tools for the macOS interface: window and app control, clicks and typing, reading the accessibility tree, AppleScript, and screen captures.
What does macOS-MCP require to work?
Python 3.11+ and UV, plus Accessibility and Screen Recording permissions granted to your terminal, Python and UV. The server supports macOS 12 and later.
