iMCP

IMCP, a macOS app requiring macOS 15.3 or later, connects Apple services such as Calendar, Contacts, Messages, and Weather to AI clients through the Model Context Protocol (MCP), starting with Claude Desktop. The app exposes 12 tools and is installable via Homebrew with the command `brew install --cask mattt/tap/iMCP`; iMCP states it does not collect or store user data, though clients like Claude Desktop send data off device as part of tool calls.

iMCP is a macOS app for connecting your digital life with AI. It works with Claude Desktop https://claude.ai/download and a growing list of clients https://modelcontextprotocol.io/clients that support the Model Context Protocol MCP https://modelcontextprotocol.io/introduction . | | Calendar | View and manage calendar events, including creating new events with customizable settings like recurrence, alarms, and availability status. | |---|---|---| | | Contacts | Access contact information about yourself and search your contacts by name, phone number, or email address. | | | Location | Access current location data and convert between addresses and geographic coordinates. | | | Maps | Provides location services including place search, directions, points of interest lookup, travel time estimation, and static map image generation. | | | Messages | Access message history with specific participants within customizable date ranges. | | | Phone | View call history synced from your iPhone, filter calls by participant, date, or call type, and start calls with system confirmation. | | | Reminders | View and create reminders with customizable due dates, priorities, and alerts across different reminder lists. | | | Shortcuts | List and run shortcuts on your Mac, with optional text input. | | | Weather | Access current weather conditions including temperature, wind speed, and weather conditions for any location. | First, download the iMCP app https://iMCP.app/download requires macOS 15.3 or later . Or, if you have Homebrew https://brew.sh 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. https://github.com/mattt/iMCP/blob/main/Assets/icon.svg 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. 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. If you don't have Claude Desktop installed, you can download it here https://claude.ai/download . 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". https://github.com/mattt/iMCP/blob/main/Assets/icon.svg 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. You can also configure Claude Desktop manually Click "Copy server command to clipboard". Then open https://github.com/mattt/iMCP/blob/main/Assets/icon.svg claude desktop config.json in your editor and enter the following: { "mcpServers": { "iMCP": { "command": "{paste iMCP server command}" } } } 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 https://claude.com/product/claude-code To add iMCP globally after installing the app: claude mcp add --scope user iMCP -- /Applications/iMCP.app/Contents/MacOS/imcp-server Or import from Claude Desktop If you've already configured Claude Desktop, you can import its MCP servers: claude mcp add-from-claude-desktop Connect to Cursor https://cursor.com Open this deep link to automatically install the iMCP server: Connect to Amp https://ampcode.com 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. iMCP is a macOS app that bundles a command-line executable, imcp-server . - iMCP.app https://github.com/mattt/iMCP/blob/main/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 https://github.com/mattt/iMCP/blob/main/CLI provides an MCP server that uses standard input/output for communication stdio transport https://modelcontextprotocol.io/docs/concepts/architecture transport-layer . The app and CLI communicate with each other on the local network using Bonjour https://developer.apple.com/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 https://github.com/mattt/iMCP/blob/8cf9d250286288b06bf5d3dda78f5905ad0d7729/CLI/main.swift L47 for implementation details. For this project, we created what became the official Swift SDK https://github.com/modelcontextprotocol/swift-sdk for Model Context Protocol servers and clients. The app uses this package to handle proxied requests from MCP clients. 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 https://developer.apple.com/documentation/security/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 https://developer.apple.com/documentation/appkit/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. 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 https://github.com/mattt/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 https://github.com/ReagentX/imessage-exporter project and blog post about reverse-engineering typedstream https://chrissardegna.com/blog/reverse-engineering-apples-typedstream-format/ . 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. The tools provided by iMCP return results as JSON-LD https://json-ld.org documents. For example, the fetchContacts tool uses the Contacts framework https://developer.apple.com/documentation/contacts , which represents people and organizations with the CNContact https://developer.apple.com/documentation/contacts/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 https://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 https://github.com/mattt/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-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. To debug interactions between iMCP and clients, you can use the inspector tool https://github.com/modelcontextprotocol/inspector requires Node.js : 1. Click 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. Companion https://github.com/mattt/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 2. Download https://github.com/mattt/Companion/releases/latest/download/Companion.zip 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" - Justin Spahr-Summers https://jspahrsummers.com/ @jspahrsummers https://github.com/jspahrsummers , David Soria Parra @dsp-ant https://github.com/dsp-ant , and Ashwin Bhat @ashwin-ant https://github.com/ashwin-ant for their work on MCP. - Christopher Sardegna https://chrissardegna.com @ReagentX https://github.com/ReagentX for reverse-engineering the typedstream format used by the Messages app. This project is available under the MIT license. See the LICENSE file for more info. iMessage® is a registered trademark of Apple Inc. This project is not affiliated with, endorsed, or sponsored by Apple Inc.