@heznpc/imcp

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:

• semantic_index — Index data from enabled Apple apps into a local vector store
• semantic_search — Search by meaning across all indexed data
• find_related — Find items related to a specific note/event/reminder
• 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

Notes (12 tools)

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

Reminders (11 tools)

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

Calendar (10 tools)

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

Contacts (10 tools)

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

Mail (9 tools)

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

Music (9 tools)

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

Finder, Safari, System, Photos, Messages, Shortcuts, Intelligence

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