The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Macuse listing page.
Give your AI direct control of Calendar, Mail, Notes, Reminders, Messages, and any other Mac app over the Model Context Protocol — an MCP server for Mac plus Computer Use for macOS, fully on-device.
Works with Claude Desktop, Cursor, Codex, Raycast, VS Code, Warp, Zed, LM Studio, Windsurf, and any MCP-compatible client.
This repo packages Macuse for agent clients: the Claude Desktop
.mcpbinstaller and the agent plugin for Claude Code and Codex. The macOS app itself and the full docs live at macuse.app.
| You use | Install this | Get |
|---|---|---|
| Claude Code, Codex | Agent plugin | MCP tools + skills |
| Claude Desktop | .mcpb bundle | MCP tools |
| Cursor, Raycast, VS Code, Zed, … | Direct command | MCP tools |
All three connect to the same local server. The plugin additionally installs skills — instructions that teach the agent how to use the tools correctly instead of discovering the parameter shapes by trial and error.
Two complementary ways for AI to work with your Mac. Everything runs locally — your data never leaves your device.
Your AI reads and writes directly to macOS apps through natural conversation.
| Toolbox | What you can ask |
|---|---|
| Calendar | "Schedule a meeting next Tuesday at 3pm", find free time, manage events |
| "Draft a reply to this email", search inbox, organize messages | |
| Notes | "Find notes mentioning the Q2 launch", capture ideas, append to notes |
| Reminders | Create tasks with due dates and priorities, mark complete, search across lists |
| Messages | Read and send iMessages, search conversations |
| Stickies | Search, read, and create sticky notes in Apple Stickies |
| Contacts | Look up by name, email, phone, or company |
| Maps & Location | Place search, directions, travel time, current location |
| Shortcuts | Browse installed Shortcuts and run them with optional input |
See and control any Mac app — even ones without a dedicated integration. Macuse brings Computer Use to macOS for any MCP client, not just Claude or Codex.
For Claude Code and Codex. Bundles the MCP server with three skills, so the agent knows the workflows, parameter formats, and permission-error recovery paths up front.
Install Macuse: download from macuse.app/download, drag Macuse.app to /Applications, and launch it once
Add the marketplace and install:
Claude Code
Codex
Approve OAuth: on the first tool call, approve the authorization prompt in the Macuse window
Restart the session (or run /reload-plugins in Claude Code) if tools do not
appear immediately. Set MACUSE_BINARY if the app is not in /Applications.
| Skill | Covers |
|---|---|
macuse-setup | Install, connect a client, grant macOS permissions, diagnose a broken setup |
macuse-apps | Calendar, Mail, Reminders, Notes, Messages, Location — routing, parameter shapes, workflow ordering |
macuse-computer-use | Driving any Mac app's GUI — inspect/act/verify loop, element targeting, error recovery |
The agent loads a skill only when the task calls for it. Details live in
plugins/macuse/README.md.
Codex users: write operations currently fail because Codex auto-declines consent prompts from third-party MCP servers (openai/codex#18896). Reads work normally.
Claude Desktop doesn't support remote http:// connectors directly, so this .mcpb is the one-click installer. For other MCP clients, see Use With Other Clients below.
Macuse.app to /Applications and launch itmacuse.mcpb from Releases and double-click to open in Claude DesktopTo uninstall, remove the entry from Claude Desktop settings.
For clients that accept a custom command (Cursor, Codex, Raycast, VS Code, Warp, Zed, LM Studio, Windsurf, ChatWise, and more), skip this bundle and configure directly:
Per-client setup guides: macuse.app/docs/clients.
Every install path is a thin shim over the same thing: macuse mcp, the CLI
built into the Macuse macOS app. All MCP protocol handling, OAuth, permissions,
and reconnection live inside the app.
.mcpb bundle is a ~130 LOC Node stdio wrapper that spawns macuse mcp and forwards JSON-RPC over stdin/stdout. It exists solely because Claude Desktop doesn't yet support http:// remote connectors directly.Override the binary path with the MACUSE_BINARY environment variable
(configurable in the Claude Desktop bundle UI). Default:
/Applications/Macuse.app/Contents/MacOS/macuse.
Both marketplaces point at plugins/macuse in this repo, so one push updates
every channel. Version strings across package.json, manifest.json, and both
plugin manifests are synced at release time by
scripts/sync-manifest-version.js.
Validate plugin changes before pushing:
.mcpb bundle only (bundled by Claude Desktop's runtime); the plugin has no Node dependencyThis MCPB bundle is MIT-licensed. The Macuse macOS application is a separate commercial product — see macuse.app for details.