mattt/iMCP

iMCP – macOS bridge between your personal data and AI tools

What it is

• A native macOS application (with a bundled CLI server) that exposes the data and services on your Mac – calendar, contacts, messages, phone calls, voicemail, reminders, weather, location, HomeKit, etc. – through the Model Context Protocol (MCP).
• MCP‑compatible AI clients such as Claude Desktop, Claude Code, Cursor, and Amp can call these services as tools, letting the LLM retrieve or act on your personal information without you having to paste it manually.

Key capabilities

Service	What you can do
Calendar	List, create and modify events (recurrence, alarms, availability).
Contacts	Query your own contact card or search contacts by name, phone or email.
Home	Discover HomeKit accessories, read/write characteristics, run scenes and automations (requires a separate helper app you sign yourself).
Location / Maps	Get current GPS, convert addresses, search places, request directions, travel‑time estimates, static map images.
Messages	Read message history for a participant over a chosen date range.
Phone	View call log, filter by contact/date/type, initiate calls (with macOS confirmation).
Voicemail	Retrieve synced voicemails, with transcript and audio, filter by sender/mailbox.
Reminders	List, create, edit, delete reminders and manage reminder lists.
Shortcuts	List and run macOS Shortcuts, optionally passing text input.
Weather	Current temperature, wind, conditions for any location.

How it works

1. MCP server – The app bundles imcp‑server, a command‑line executable that speaks MCP over standard I/O.
2. Discovery – The app and server advertise a _mcp._tcp service via Bonjour, so any MCP client on the same Mac can find them automatically.
3. Permission handling – When you enable a service, macOS shows the usual permission dialog (e.g., Full Access to Calendar). The app stores the granted sandbox access (folder picks for Messages, Call History, Voicemail, etc.) and uses it to read the underlying SQLite databases.
4. Data format – Tool results are returned as JSON‑LD using the Schema.org vocabulary (e.g., a contact becomes a Person object). This makes the output easy for LLMs and other software to consume.
5. HomeKit support – Because HomeKit is only available to Mac Catalyst apps, iMCP ships a separate iMCP Helper that you must build and sign with your own Apple Developer account. The main app talks to the helper over a local TCP port.

Installation

• Download the signed app from https://iMCP.app/download (requires macOS 15.3+), or install via Homebrew:

  brew install --cask mattt/tap/iMCP
  

• The app places an icon in the menu bar; toggle the blue switch to start the MCP server.
• Enable the services you need; each will prompt for the appropriate macOS permission.
• (Optional) Build the HomeKit helper if you want Home automation:

  git clone https://github.com/mattt/iMCP.git
  cd iMCP
  Scripts/install-helper.sh   # signs and installs the helper
  

Connecting an AI client

• Claude Desktop – Open Settings → Developer → Edit Config, then use the Configure Claude Desktop menu item in iMCP. This writes a server entry to claude_desktop_config.json. After restarting Claude, the tool list shows a hammer icon (🔨) with the 12 iMCP tools.
• Claude Code, Cursor, Amp – Each provides a CLI command (claude mcp add …, cursor …, amp mcp add …) that registers the iMCP server globally. Deep‑link URLs are also supplied for Cursor.

Debugging & inspection

• Local‑network permission – imcp‑server needs the Local Network privacy permission; enable it in System Settings > Privacy & Security.
• MCP Inspector – Run npx @modelcontextprotocol/inspector <server‑command> to open a web UI that shows every request/response between a client and iMCP.
• Companion – A macOS 15+ utility for interactively browsing a server’s prompts, resources, and tools.

Who it’s for

• Developers building AI‑augmented macOS experiences who need a secure, privacy‑first way to expose personal data to LLMs.
• Power users who want their AI assistants (Claude, Cursor, etc.) to answer questions like “What’s the weather where I am?” or “Schedule a meeting with Alice next Tuesday at 3 pm” without manually copying data.
• Anyone interested in the Model Context Protocol; iMCP also serves as a reference implementation and ships the official Swift SDK for MCP.

Why it matters

• Keeps your personal data on‑device; iMCP never stores or transmits anything itself. The AI client decides what to send.
• Provides a uniform, typed interface (JSON‑LD) that many LLMs can consume, reducing the need for custom scraping or manual export scripts.
• Demonstrates how macOS system services can be safely bridged to modern AI tool‑calling workflows.