iMCP

iMCP is a macOS app for connecting your digital life with AI. It works with Claude Desktop and a growing list of clients that support the Model Context Protocol (MCP).

Capabilities

Getting Started

Download and open the app

First, download the iMCP app (requires macOS 15.3 or later).

Or, if you have Homebrew installed, you can run the following command:

brew install --cask mattt/tap/iMCP

When you open the app, you'll see a icon in your menu bar.

Clicking on this icon reveals the iMCP menu, which displays all available services. Initially, all services will appear in gray, indicating they're inactive.

The blue toggle switch at the top indicates that the MCP server is running and ready to connect with MCP-compatible clients.

Activate services

To activate a service, click on its icon. The system will prompt you with a permission dialog. For example, when activating Calendar access, you'll see a dialog asking "iMCP" Would Like Full Access to Your Calendar. Click Allow Full Access to continue.

[!IMPORTANT] iMCP does not collect or store any of your data. Clients like Claude Desktop do send your data off device as part of tool calls.

Once activated, each service icons goes from gray to their distinctive colors — red for Calendar, green for Messages, blue for Location, and so on.

Repeat this process for all of the capabilities you'd like to enable. These permissions follow Apple's standard security model, giving you complete control over what information iMCP can access.

Connect to Claude Desktop

If you don't have Claude Desktop installed, you can download it here.

Open Claude Desktop and go to "Settings... (⌘,)". Click on "Developer" in the sidebar of the Settings pane, and then click on "Edit Config". This will create a configuration file at ~/Library/Application Support/Claude/claude_desktop_config.json.

To connect iMCP to Claude Desktop, click > "Configure Claude Desktop".

This will add or update the MCP server configuration to use the imcp-server executable bundled in the application. Other MCP server configurations in the file will be preserved.

Click > "Copy server command to clipboard". Then open claude_desktop_config.json in your editor and enter the following:

{
  "mcpServers": {
    "iMCP": {
      "command": "{paste iMCP server command}"
    }
  }
}

Call iMCP tools from Claude Desktop

Quit and reopen the Claude Desktop app. You'll be prompted to approve the connection.

After approving the connection, you should now see 🔨12 in the bottom right corner of your chat box. Click on that to see a list of all the tools made available to Claude by iMCP.

Now you can ask Claude questions that require access to your personal data, such as:

"How's the weather where I am?"

Claude will use the appropriate tools to retrieve this information, providing you with accurate, personalized responses without requiring you to manually share this data during your conversation.

Connect to Claude Code

To add iMCP globally after installing the app:

claude mcp add --scope user iMCP -- /Applications/iMCP.app/Contents/MacOS/imcp-server

If you've already configured Claude Desktop, you can import its MCP servers:

claude mcp add-from-claude-desktop

Connect to Cursor

Open this deep link to automatically install the iMCP server:

Connect to Amp

To add iMCP globally (available in all projects):

amp mcp add iMCP -- /Applications/iMCP.app/Contents/MacOS/imcp-server

[!NOTE] When a client first connects, iMCP will show an approval dialog. Click "Allow" and check "Always trust this client" to avoid repeated prompts.

Technical Details

App & CLI

iMCP is a macOS app that bundles a command-line executable, imcp-server.

• iMCP.app provides UI for configuring services and — most importantly — a means of interacting with macOS system permissions, so that it can access Contacts, Calendar, and other information.
• imcp-server provides an MCP server that uses standard input/output for communication (stdio transport).

The app and CLI communicate with each other on the local network using Bonjour for automatic discovery. Both advertise a service with type "_mcp._tcp" and domain "local". Requests from MCP clients are read by the CLI from stdin and relayed to the app; responses from the app are received by the CLI and written to stdout. See StdioProxy for implementation details.

For this project, we created what became the official Swift SDK for Model Context Protocol servers and clients. The app uses this package to handle proxied requests from MCP clients.

iMessage Database Access

Apple doesn't provide public APIs for accessing your messages. However, the Messages app on macOS stores data in a SQLite database located at ~/Library/Messages/chat.db.

iMCP runs in App Sandbox, which limits its access to user data and system resources. When you go to enable the Messages service, you'll be prompted to select your ~/Library/Messages folder through the standard file picker. When you do, macOS adds that folder to the app's sandbox. NSOpenPanel is magic like that. The folder matters: chat.db is a WAL-mode database, and Messages writes every new message to chat.db-wal next to it first, only folding the log into chat.db at a checkpoint every few MB — often hours later. A grant on chat.db alone (what earlier versions asked for) leaves that log unreadable, so the newest messages were missing until then. If you granted chat.db with an earlier version, Messages keeps working from the last checkpoint; switch Messages off and on in the iMCP menu to grant the folder instead.

Attachment files are a separate matter. The sandbox walls off ~/Library/Messages/Attachments from a grant on its parent folder, so reading message attachments (messages_attachment_read) asks for that subfolder through the same picker — a second, read-only grant of its own. Granting it is optional: declining leaves messages_attachment_read unable to read files, while everything else keeps working. If you granted the Messages folder before attachments were supported, switch Messages off and on in the iMCP menu to be asked for it.

But opening the iMessage database is just half the battle. Over the past few years, Apple has moved away from storing messages in plain text and instead toward a proprietary typedstream format.

For this project, we created Madrid: a Swift package for reading your iMessage database. It includes a Swift implementation for decoding Apple's typedstream format, adapted from Christopher Sardegna's imessage-exporter project and blog post about reverse-engineering typedstream.

Call History Database Access

Call history synced from your iPhone lives in a SQLite database at ~/Library/Application Support/CallHistoryDB/CallHistory.storedata. Recent calls sit in its write-ahead log next to the store file, so the Phone service asks you to open the CallHistoryDB folder rather than the file alone.

Visual Voicemail Database Access

Voicemails synced from your iPhone by the Phone app (on macOS 26 and later) live in a SQLite database at ~/Library/Group Containers/group.com.apple.FaceTime/com.apple.facetimemessagestored/Data Store/FaceTimeMessageStore-local.sqlitedb. The store is a write-ahead log database, and the message audio sits in an Assets tree beside it, so the Voicemail service asks you to open the Data Store folder rather than the file alone.

JSON-LD for Tool Results

The tools provided by iMCP return results as JSON-LD documents. For example, the fetchContacts tool uses the Contacts framework, which represents people and organizations with the CNContact type. Here's how an object of that type is encoded as JSON-LD:

{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "Mattt",
  "url": "https://mat.tt"
}

Schema.org provides standard vocabularies for people, postal addresses, events, and many other objects we want to represent. And JSON-LD is a convenient encoding format for humans, AI, and conventional software alike.

For this project, we created Ontology: a Swift package for working with structured data. It includes convenience initializers for types from Apple frameworks, such as those returned by iMCP tools.

iMCP Helper

Apple doesn't make the HomeKit framework available to native macOS apps, only to Mac Catalyst apps. So the Home service runs in a separate Catalyst app, iMCP Helper. Apple doesn't allow HomeKit in Developer ID apps, so iMCP's release build doesn't include the helper. Build and install it with your own Apple Developer account:

git clone https://github.com/mattt/iMCP.git
cd iMCP
Scripts/install-helper.sh

The script signs the helper with your team's development certificate and installs it in /Applications. Run it with --help to choose another team, bundle ID, or install directory. Xcode must be signed in to your account (Xcode > Settings > Accounts), and the helper runs only on Macs registered to your team. Whether free personal teams can use HomeKit isn't verified. Then turn on Home in iMCP. iMCP finds the helper in /Applications. If you installed it somewhere else, iMCP asks you to choose it when you turn on Home, or you can choose it in Settings > Services > Home. When you enable Home, iMCP launches the helper and the helper asks for HomeKit access. The helper exits when iMCP exits, and its status window reports startup and permission errors. The Mac's iCloud account must have access to the home, and writes can require the owner or administrator role.

Both apps compile the same tool definitions from Shared/Home/HomeTools.swift. The helper implements them with HomeKit; the app forwards each call over an MCP connection on the loopback interface, so the usual service and per-tool switches apply. Object IDs are HomeKit UUID strings. Inventory tools return live characteristic values only when include_values is true, with a five-second timeout and at most four outstanding HomeKit reads. After a lost connection, read-only calls retry once. Writes are not repeated, because HomeKit may have applied them already; the error asks the caller to inspect the home before retrying.

iMCP passes an ephemeral loopback port to the helper it launches. A helper started some other way (for example, from Xcode) advertises "_imcp-helper._tcp" on the local-only DNS-SD interface instead. If iMCP can't find such a helper, quit it and let iMCP launch its own. To point imcp-server (and so the MCP Inspector) at a running helper directly, set IMCP_SERVICE_TYPE=_imcp-helper._tcp. uv run Scripts/check-home.py <path-to-imcp-server> runs a read-only integration check against it.

Building the helper

Building the iMCP scheme runs Scripts/build-helper.sh, which builds the iMCP Helper scheme for Mac Catalyst in its own derived-data directory and copies the product into the app. A direct target dependency selects the iOS variant of the helper, so the nested build is required. Release builds set EMBED_HOME_HELPER = NO and leave the helper out.

The HomeKit entitlement requires a development certificate and a provisioning profile with the HomeKit capability. So the helper uses automatic signing with team TTY35UM57S in both Debug and Release, even though the native Debug app is unsigned. To build with another team, change it in the helper target's Signing & Capabilities tab. The first Mac Catalyst build for a new bundle ID can fail with "Entitlement com.apple.developer.homekit not found and could not be included in profile", because automatic provisioning registers the capability only for the iOS destination. Scripts/install-helper.sh handles this by building for iOS once and retrying. To do it by hand, build the helper once for iOS to register it, then build for Mac Catalyst:

xcodebuild -scheme "iMCP Helper" -destination "generic/platform=iOS" \
  -allowProvisioningUpdates build
xcodebuild -scheme "iMCP Helper" -destination "platform=macOS,variant=Mac Catalyst" \
  -allowProvisioningUpdates build

CI builds both apps unsigned, which checks compilation and packaging but can't access HomeKit:

xcodebuild -scheme iMCP -configuration Debug -destination "platform=macOS" \
  CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO \
  HELPER_CODE_SIGNING_ALLOWED=NO build

Debugging

Allowing local network access

imcp-server finds the iMCP app with Bonjour, so it needs permission to access the local network. imcp-server has its own entry in System Settings > Privacy & Security > Local Network, separate from iMCP and from the app that runs it, such as your terminal. If that entry is turned off, imcp-server can't find the app and reports that Bonjour service discovery timed out.

Using the MCP Inspector

To debug interactions between iMCP and clients, you can use the inspector tool (requires Node.js):

1. Click > "Copy server command to clipboard"

2. Open a terminal and run the following commands:

   # Download and run inspector package on imcp-server
   npx @modelcontextprotocol/inspector [paste-copied-command]
   
   # Open inspector web app running locally
   open http://127.0.0.1:6274
   

Inspector lets you see all requests and responses between the client and the iMCP server, which is helpful for understanding how the protocol works.

Using Companion

Companion is a utility for testing and debugging your MCP servers (requires macOS 15 or later). It gives you an easy way to browse and interact with a server's prompts, resources, and tools. Here's how to connect it to iMCP:

1. Click > "Copy server command to clipboard"
2. Download and open the Companion app
3. Click the + button in the toolbar to add an MCP server
4. Fill out the form:
   • Enter "iMCP" as the name
   • Select "STDIO" as the transport
   • Paste the copied iMCP server command
   • Click "Add Server"

Acknowledgments

• Justin Spahr-Summers (@jspahrsummers), David Soria Parra (@dsp-ant), and Ashwin Bhat (@ashwin-ant) for their work on MCP.
• Christopher Sardegna (@ReagentX) for reverse-engineering the typedstream format used by the Messages app.

License

This project is available under the MIT license. See the LICENSE file for more info.

Legal

iMessage® is a registered trademark of Apple Inc. This project is not affiliated with, endorsed, or sponsored by Apple Inc.