Macuse — AI Superpowers for Every Mac App
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 .mcpb installer and the agent plugin for Claude Code and Codex. The macOS app itself and the full docs live at macuse.app.
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.
What Macuse Does
Two complementary ways for AI to work with your Mac. Everything runs locally — your data never leaves your device.
Native App Integrations
Your AI reads and writes directly to macOS apps through natural conversation.
Computer Use on macOS
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.
- Click any element, type text, navigate menus, drive any app
- Fill out web forms, operate enterprise software, automate APIs that don't exist
- Runs in the background — your cursor and active window stay untouched while AI works in another app
Install as an Agent Plugin
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
/plugin marketplace add macuse-app/macuse-mcp
/plugin install macuse@macuse-plugins
Codex
codex plugin marketplace add macuse-app/macuse-mcp
codex plugin add macuse@macuse-plugins
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.
Skills Included
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.
Install for Claude Desktop
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.
- Install Macuse:
- Download from macuse.app/download
- Drag
Macuse.app to /Applications and launch it
- Grant the permissions the app prompts for
- Install the bundle: download
macuse.mcpb from Releases and double-click to open in Claude Desktop
- Approve OAuth: approve the authorization prompt that pops up — connection done
To uninstall, remove the entry from Claude Desktop settings.
Use With Other MCP Clients
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:
{
"mcpServers": {
"macuse": {
"command": "/Applications/Macuse.app/Contents/MacOS/macuse",
"args": ["mcp"]
}
}
}
Per-client setup guides: macuse.app/docs/clients.
Privacy & Permissions
- Local-only. All processing stays on your Mac. No cloud, no telemetry of your content.
- Per-app permissions. Allow, deny, or one-time-approve each AI client for each app it touches. Sensitive apps like password managers and banking re-confirm every time. Revoking an AI client automatically clears its app permissions.
- Per-client OAuth. Each MCP client gets its own authorization, manageable in Macuse settings.
How This Works
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.
- The
.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.
- The plugin skips Node entirely — a shell launcher execs the same binary, and adds the skills on top.
Override the binary path with the MACUSE_BINARY environment variable
(configurable in the Claude Desktop bundle UI). Default:
/Applications/Macuse.app/Contents/MacOS/macuse.
Repo Layout
.claude-plugin/marketplace.json Claude Code marketplace catalog
.agents/plugins/marketplace.json Codex marketplace catalog
plugins/macuse/ The plugin — manifests, launcher, skills
src/, bin/ Node stdio wrapper for the .mcpb bundle
manifest.json .mcpb bundle manifest (Claude Desktop)
server.json MCP Registry entry
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:
claude plugin validate ./plugins/macuse --strict # plugin manifest
claude plugin validate . --strict # marketplace catalog
Requirements
- macOS 13.0 (Ventura) or later — Apple Silicon or Intel
- Macuse macOS app installed
- Node 20.8.1+ for the
.mcpb bundle only (bundled by Claude Desktop's runtime); the plugin has no Node dependency
Links
License
This MCPB bundle is MIT-licensed. The Macuse macOS application is a separate commercial product — see macuse.app for details.
