@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.

한국어

Features

• 110 tools across 13 modules — full CRUD for Apple apps + system control + Apple Intelligence
• 20 prompts — per-app workflows + cross-module + developer workflows (dev-session, debug-loop, build-log)
• 4 MCP Resources — live data URIs for notes, calendar, and reminders
• JXA + Swift bridge — JXA for core automation, EventKit/PhotoKit via Swift for advanced features
• Recurring events/reminders — create recurrence rules via EventKit (macOS 26+ Swift bridge)
• Photos import/delete — import and delete photos via PhotoKit (macOS 26+ Swift bridge)
• Apple Intelligence — on-device summarization, rewriting, proofreading (macOS 26+)
• Native menubar app — SwiftUI companion app for status monitoring, permission setup, config copy
• One-click setup — setup_permissions tool or menubar app triggers all macOS permission prompts at once
• stdio transport — secure local communication, no network exposure
• Safety annotations — every tool tagged with readOnly/destructive hints

Quick Start

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

Menubar App (Optional)

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

cd app && swift build -c release
# Binary: app/.build/release/iMcpApp

Features: server status indicator, one-click permission setup, copy Claude config to clipboard.

Tools

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 (8 tools)

Tool	Description	Type
search_files	Spotlight search in a folder	read
get_file_info	File size, dates, kind, tags	read
set_file_tags	Set Finder tags on a file	destructive
recent_files	Recently modified files	read
list_directory	List files in a directory	read
move_file	Move or rename a file	destructive
trash_file	Move file to Trash	destructive
create_folder	Create a new folder	write

Safari (8 tools)

Tool	Description	Type
list_tabs	List all open tabs across windows	read
read_page_content	Read text content of a page	read
get_current_tab	Get the active tab URL and title	read
open_url	Open a URL in Safari	write
close_tab	Close a specific tab	destructive
activate_tab	Switch to a specific tab	write
run_javascript	Execute JavaScript in a tab	write
search_tabs	Search tabs by title or URL	read

System (10 tools)

Tool	Description	Type
get_clipboard	Read clipboard contents	read
set_clipboard	Write to clipboard	write
get_volume	Get system volume level	read
set_volume	Set system volume level	write
toggle_dark_mode	Toggle dark/light mode	write
get_frontmost_app	Get the frontmost application	read
list_running_apps	List all running applications	read
get_screen_info	Get display information	read
show_notification	Display a system notification	write
capture_screenshot	Take a screenshot (fullscreen/window/selection)	write

Photos (9 tools)

Tool	Description	Type
list_albums	List photo albums	read
list_photos	List photos in an album	read
search_photos	Search photos by keyword	read
get_photo_info	Detailed photo metadata	read
list_favorites	List favorite photos	read
create_album	Create a new album	write
add_to_album	Add photos to an album	write
import_photo	Import from file path (Swift/PhotoKit)	write
delete_photos	Delete photos by ID (Swift/PhotoKit)	destructive

Messages (6 tools)

Tool	Description	Type
list_chats	List recent chats with participants	read
read_chat	Read chat details including participants and last update	read
search_chats	Search by name, participant, or handle	read
send_message	Send text via iMessage/SMS	write
send_file	Send file attachment via iMessage/SMS	write
list_participants	List participants in a chat	read

Shortcuts (4 tools)

Tool	Description	Type
list_shortcuts	List available Shortcuts	read
run_shortcut	Run a Shortcut by name	write
search_shortcuts	Search shortcuts by name	read
get_shortcut_detail	Get shortcut details/actions	read

Apple Intelligence (3 tools)

Requires macOS 26+ with Apple Silicon. Graceful error on unsupported systems.

Tool	Description	Type
summarize_text	On-device summarization	read
rewrite_text	Rewrite in specified tone	read
proofread_text	Grammar/spelling correction	read

Resources

MCP Resources expose live data from Apple apps as URIs.

URI	Description
notes://recent	10 most recent notes
notes://recent/{count}	Recent notes (configurable count)
calendar://today	Today's calendar events
reminders://due	Overdue reminders

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
• research-with-safari — Browse with Safari + save findings to Notes
• focus-session — Calendar + Reminders + Music for focused work
• file-organizer — Organize files with Finder + track in Notes

Developer Workflows

• dev-session — Scan project, check specs, research docs, create session notes
• debug-loop — Capture errors from Safari/clipboard, locate code, log bugs, create fix tasks
• screen-capture-flow — Screenshot → Photos import → annotated note
• app-release-prep — Calendar dates + changelog from Notes + Reminders checklist
• idea-to-task — Break idea into tasks → Reminders + Calendar time blocks
• build-log — Analyze build output, log errors or celebrate success with Music

Developer Agent Pipeline

iMcp's developer prompts chain Apple apps into autonomous agent workflows. Each prompt orchestrates multiple tools across modules — the AI reads your actual filesystem, Notes, Calendar, and Reminders to build real context, then writes back structured results.

┌─────────────────────────────────────────────────────────────────┐
│                     dev-session                                 │
│  Finder (scan) → Notes (specs) → Safari (docs) → Notes (log)   │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                     debug-loop                                  │
│  Safari (JS errors) → Clipboard → Finder (locate) →            │
│  Notes (bug log) → Reminders (fix task)                         │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                     idea-to-task                                 │
│  Notes (capture) → AI (decompose) → Reminders (tasks) →        │
│  Calendar (time blocks)                                         │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                     build-log                                   │
│  Finder (output) → Clipboard (log) →                            │
│  ┌ fail → Notes (error log) → Reminders (fix task)              │
│  └ pass → Notification → Music (celebrate) → Notes (success)    │
└─────────────────────────────────────────────────────────────────┘

These prompts are designed for AI coding agents (Claude Code, Cursor, Copilot) to invoke as MCP prompts — turning your Mac into a context-aware development environment.

Demo video coming soon.

Configuration

Environment Variable	Default	Description
IMCP_INCLUDE_SHARED	false	Include shared notes/folders in results

Requirements

• macOS (Apple apps require macOS)
• Node.js >= 18
• First run will prompt for Automation permission for each app — use setup_permissions tool to grant all at once
• 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. Read first to preserve content.
• Password-protected notes unreadable.

Reminders / Calendar

• JXA recurrence rules are read-only — use create_recurring_event/create_recurring_reminder (Swift/EventKit) to create recurring items
• Calendar attendees are read-only

Contacts

• Custom fields not accessible

Mail

• Content truncated to 5000 characters by default (configurable via maxLength parameter)

Messages

• Chat message history (individual message content) is not accessible via JXA
• Send requires the recipient to be a known buddy in the Messages service

Music

• Smart playlists are read-only
• No queue manipulation

Finder

• Tags use Spotlight (mdfind), performance varies with index state

Safari

• Reading page content requires Allow JavaScript from Apple Events in Safari Developer menu

Photos

• JXA: albums can be created and photos added, but no import/delete
• Swift bridge (macOS 26+): full import and delete via PhotoKit

Apple Intelligence

• Requires macOS 26 (Tahoe) + Apple Silicon
• Run npm run swift-build to compile the bridge binary

License

MIT