iMcp

MCP server for the entire Apple ecosystem — Notes, Reminders, Calendar, Contacts, Mail, Messages, Music, Finder, Safari, System, Photos, Shortcuts, and Apple Intelligence. Connect any AI to your Mac.

한국어

Get Started (2 minutes)

1. Install Node.js

If you don't have Node.js, install it first:

# Using Homebrew (recommended)
brew install node

# Or download from https://nodejs.org (LTS version)

2. Run the Setup Wizard

npx @heznpc/imcp init

This will:

• Let you choose which Apple apps to connect (Notes, Calendar, Reminders, etc.)
• Automatically configure Claude Desktop
• Save your preferences to ~/.config/imcp/config.json

3. Restart Claude Desktop

That's it! Claude can now read your notes, manage reminders, check your calendar, and more.

Troubleshooting

npx @heznpc/imcp doctor

Checks Node.js version, config files, Claude Desktop setup, macOS permissions, and module status — all in one command.

What Can It Do?

122 tools across 14 Apple app modules + semantic search, 9 MCP resources, and 20 prompts:

| Module | What it does | Tools | |--------|-------------|-------| | Notes | Read, create, search, organize notes and folders | 12 | | Reminders | Create tasks, set due dates, manage lists | 11 | | Calendar | View events, create meetings, check schedule | 10 | | Contacts | Look up people, manage contact info | 10 | | Mail | Read, search, send, reply to emails | 11 | | Music | Control playback, search tracks, manage playlists | 9 | | Finder | Browse files, search with Spotlight, organize | 8 | | Safari | Read web pages, manage tabs | 8 | | System | Clipboard, volume, dark mode, screenshots, notifications | 10 | | Photos | Browse albums, import/delete photos | 9 | | Messages | View chats, send iMessages | 6 | | Shortcuts | Run Siri Shortcuts from AI | 4 | | Intelligence | On-device summarize, rewrite, proofread (macOS 26+) | 3 | | TV | Browse library, control playback, search content | 6 | | Semantic | On-device cross-app semantic search (Swift bridge) | 4 |

All tools include MCP annotations (readOnlyHint, destructiveHint, openWorldHint) for client-side safety UI.

Module Presets

By default, new installations start with 5 core modules (Notes, Reminders, Calendar, Shortcuts, System) to keep things simple. You can enable more anytime:

# Re-run the setup wizard to change modules
npx @heznpc/imcp init

# Or enable all modules at once
npx @heznpc/imcp --full

Or edit ~/.config/imcp/config.json directly:

{
  "disabledModules": ["messages", "intelligence"]
}

CLI Commands

| Command | Description | |---------|-------------| | npx @heznpc/imcp init | Interactive setup wizard | | npx @heznpc/imcp doctor | Diagnose installation issues | | npx @heznpc/imcp | Start MCP server (stdio, default) | | npx @heznpc/imcp --full | Start with all 13 modules enabled | | npx @heznpc/imcp --http | Start as HTTP server (port 3847) |

Alternative Setup (Manual)

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "imcp": {
      "command": "npx",
      "args": ["-y", "@heznpc/imcp"]
    }
  }
}

Claude Code

claude mcp add imcp -- npx -y @heznpc/imcp

Local Development

git clone https://github.com/heznpc/iMcp.git
cd iMcp
npm install
npm run build
node dist/index.js

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | IMCP_INCLUDE_SHARED | false | Include shared notes/folders | | IMCP_ALLOW_SEND_MESSAGES | true | Allow sending iMessages | | IMCP_ALLOW_SEND_MAIL | true | Allow sending emails | | IMCP_FULL | false | Enable all modules (ignores preset) | | IMCP_DISABLE_{MODULE} | — | Disable a specific module (e.g. IMCP_DISABLE_MUSIC=true) | | GEMINI_API_KEY | — | Google Gemini API key for higher-quality embeddings (optional) |

Config File

~/.config/imcp/config.json:

{
  "disabledModules": ["messages", "intelligence"],
  "includeShared": false,
  "allowSendMessages": true,
  "allowSendMail": true,
  "hitl": {
    "level": "destructive-only",
    "timeout": 30
  }
}

Advanced Features

HTTP Mode

Run iMcp as an HTTP server for remote agents or multi-client setups:

npx @heznpc/imcp --http --port 3847

Human-in-the-Loop (HITL)

Require manual approval before destructive operations:

{
  "hitl": {
    "level": "destructive-only",
    "timeout": 30
  }
}

Levels: off, destructive-only, all-writes, all

Menubar App (Optional)

A native SwiftUI companion app for server status monitoring and permission setup:

cd app && swift build -c release

Semantic Search (Optional)

On-device cross-app semantic search powered by Apple's NLContextualEmbedding. Find related notes, events, reminders, and emails by meaning — not just keywords.

npm run swift-build  # Build the Swift bridge first

Then use the tools:

1. semantic_index — Index data from enabled Apple apps into a local vector store
2. semantic_search — Search by meaning across all indexed data
3. find_related — Find items related to a specific note/event/reminder
4. semantic_status — Check index status

Supports Korean, English, Japanese, Chinese with automatic language detection. Optionally set GEMINI_API_KEY for higher-quality Google Gemini embeddings.

Swift Bridge (Optional)

For semantic search, recurring events/reminders (EventKit), photo import/delete (PhotoKit), and Apple Intelligence — requires macOS 26+:

npm run swift-build

Tools Reference

| Tool | Description | Type | |------|-------------|------| | list_notes | List all notes with title, folder, dates | read | | search_notes | Search by keyword in title and body | read | | read_note | Read full content by ID | read | | create_note | Create a note with HTML body | write | | update_note | Replace entire body | destructive | | delete_note | Delete (moved to Recently Deleted) | destructive | | move_note | Move to another folder | destructive | | list_folders | List folders with note counts | read | | create_folder | Create a new folder | write | | scan_notes | Bulk scan with metadata and preview | read | | compare_notes | Compare 2-5 notes side by side | read | | bulk_move_notes | Move multiple notes at once | destructive |

| Tool | Description | Type | |------|-------------|------| | list_reminder_lists | List all lists with counts | read | | list_reminders | Filter by list/completed | read | | read_reminder | Full details by ID | read | | create_reminder | Create with due date/priority | write | | update_reminder | Update properties | destructive | | complete_reminder | Mark complete/incomplete | write | | delete_reminder | Delete permanently | destructive | | search_reminders | Search by keyword in name/body | read | | create_reminder_list | Create a new reminder list | write | | delete_reminder_list | Delete a reminder list | destructive | | create_recurring_reminder | Create with recurrence rule (Swift/EventKit) | write |

| Tool | Description | Type | |------|-------------|------| | list_calendars | List calendars with name/color | read | | list_events | Events in date range with pagination | read | | read_event | Full details with attendees | read | | create_event | Create with location/description | write | | update_event | Update properties | destructive | | delete_event | Delete permanently | destructive | | search_events | Keyword search in date range | read | | get_upcoming_events | Next N events from now | read | | today_events | All events for today | read | | create_recurring_event | Create with recurrence rule (Swift/EventKit) | write |

| Tool | Description | Type | |------|-------------|------| | list_contacts | List with email/phone, pagination | read | | search_contacts | Search by name, email, phone, or org | read | | read_contact | Full details (emails, phones, addresses) | read | | create_contact | Create with email/phone/org | write | | update_contact | Update properties | destructive | | delete_contact | Delete permanently | destructive | | list_groups | List contact groups | read | | add_contact_email | Add email to existing contact | write | | add_contact_phone | Add phone to existing contact | write | | list_group_members | List contacts in a group | read |

| Tool | Description | Type | |------|-------------|------| | list_mailboxes | List mailboxes with unread counts | read | | list_messages | Recent messages in a mailbox | read | | read_message | Full message content | read | | search_messages | Search by subject/sender | read | | mark_message_read | Mark read/unread | write | | flag_message | Flag/unflag a message | write | | get_unread_count | Total unread across all mailboxes | read | | move_message | Move message to another mailbox | destructive | | list_accounts | List all mail accounts | read |

| Tool | Description | Type | |------|-------------|------| | list_playlists | List playlists with track counts | read | | list_tracks | Tracks in a playlist | read | | now_playing | Current track and playback state | read | | playback_control | Play, pause, next, previous | write | | search_tracks | Search by name/artist/album | read | | play_track | Play a specific track by name | write | | play_playlist | Start playing a playlist | write | | get_track_info | Detailed track metadata | read | | set_shuffle | Set shuffle and repeat mode | write |

See the full tool list in the Tools Reference or run the server to explore via your AI client.

Prompts

Per-App

• organize-notes — Classify notes by topic, create folders, move
• find-duplicates — Find similar notes, compare, suggest cleanup
• weekly-review — Summarize past week's notes
• organize-reminders — Scan, identify overdue/completed, cleanup
• daily-review — Today's due reminders with priorities
• schedule-review — Upcoming events, conflicts, optimizations
• meeting-prep — Event details + related notes for meeting prep

Cross-Module

• daily-briefing — Today's events + due reminders + recent notes
• weekly-digest — Past N days: events + notes + reminders combined
• meeting-notes-to-reminders — Extract action items from meeting notes, create reminders
• event-follow-up — Create follow-up note and reminders after a meeting

Developer Workflows

• dev-session — Scan project, check specs, research docs, create session notes
• debug-loop — Capture errors from Safari/clipboard, locate code, log bugs
• idea-to-task — Break idea into tasks → Reminders + Calendar time blocks
• build-log — Analyze build output, log errors or celebrate success

Requirements

• macOS (Apple apps require macOS)
• Node.js >= 18
• Apple Intelligence tools require macOS 26+ with Apple Silicon

Limitations

• Notes: Move copies and deletes (new ID, reset dates, lost attachments). Update replaces entire body.
• Calendar/Reminders: JXA recurrence is read-only — use Swift bridge for recurring items.
• Messages: Chat message history not accessible via JXA. Send requires known buddy.
• Safari: Reading page content requires "Allow JavaScript from Apple Events" in Safari Developer menu.
• Photos: Full import/delete requires Swift bridge (macOS 26+).

License

MIT