macos

English | 繁體中文 | 简体中文

$ macos_get_capabilities
{"data": {"platform": "darwin", "tools": [ 64 tools, each with "available": true ],
  "permissions": {"calendar": "full_access", "reminders": "full_access", "screen_recording": "granted",
    "notes_automation": "target_not_running", "mail_automation": "granted", "safari_automation": "granted"}}}

Your notes, calendar and reminders hold most of what you plan. This plugin gives Codex and Claude Code 64 tools for the native apps. Calendar and Reminders work through EventKit, so they never open the apps.

Features

• Reads and writes Notes: accounts, folders, search, create, update, append and delete (13 tools).

• Plans with Calendar: events with complex recurrence, conflicts and free slots, without opening Calendar (14 tools).

• Tracks Reminders: lists and tasks, with search and completion, without opening Reminders (13 tools).

• Drafts Mail and reads Safari: message search and draft editing (10 tools), tabs, page text and JavaScript (8 tools).

• Captures the screen: full screen, a region, a window or the clipboard (5 tools).

Related MCP server: macOS Automation MCP Server

Quick start

claude plugin marketplace add zyx1121/marketplace
claude plugin install macos@zyx1121

Codex: codex plugin marketplace add zyx1121/marketplace, then codex plugin add macos@zyx1121. Open a new session and ask "What is on my calendar tomorrow?".

The plugin needs macOS, Bun and uv. In System Settings > Privacy & Security, give the MCP host these permissions:

• full access to Calendar and Reminders

• Automation for Notes, Mail and Safari

• Screen Recording, for screenshots

Usage

• Ask in plain words, such as "read my coursework note and create reminders for its deadlines". The agent picks the tools. The server does not guess deadlines or sync apps by itself.

• Writes use IDs. An update or delete needs the ID, expected_revision and confirm=true. After a conflict, read the item again.

• A create needs an explicit container and a request_key. A retry returns the first saved response.

• The full contract, with names and examples, is in docs/productivity-api.md.

Configuration

Results mark each truncation. Never replace a note body with truncated content.

How it works

The Bun MCP server registers the tools for the host and hides the ones with a missing dependency, with the reason on stderr. Notes uses Apple Events through JXA, so it can open Notes in the background. Calendar and Reminders use EventKit for reads and writes. Mail, Safari and screenshots use AppleScript and the system capture tools. scripts/productivity.py OPERATION takes the same JSON on stdin as the MCP tools.

Limits

• macOS only. On Linux, only the diagnostics tool registers.

• The permissions belong to the MCP host app, so a terminal and a desktop app can differ.

• Notes automation can open Notes in the background.

For AI agents

Facts for coding agents and LLM tools. The rules for changing the code are in AGENTS.md.

• Summary: Claude Code and Codex plugin with 64 MCP tools for Notes, Calendar, Reminders, Mail, Safari and screenshots on macOS.

• Type: plugin

• Interfaces: MCP macos (stdio, dist/server.js). scripts/productivity.py OPERATION takes JSON on stdin.

• Install: claude plugin install macos@zyx1121, after claude plugin marketplace add zyx1121/marketplace

• Run: the host starts the MCP server

• Verify: call macos_get_capabilities and read the permissions object

• Config: MACOS_MCP_MAX_STRING_CHARS, MACOS_MCP_MAX_TOTAL_CHARS, MACOS_MCP_STATE_DIR

• Secrets: none. Retry claims stay in ~/Library/Application Support/zyx1121/macos/.

• Limits: macOS only. Writes need IDs, expected_revision and confirm=true.

Development

bun install --frozen-lockfile
bun run check

The offline tests never touch personal apps. Release Please opens the release PR, and the marketplace pins each release commit.

License

MIT