iMCP

What is iMCP?

iMCP is a macOS application designed to connect your digital life with AI, specifically by providing a Model Context Protocol (MCP) server for various Apple services like Messages, Contacts, Reminders, and more. It acts as a bridge, allowing AI clients like Claude Desktop to securely access and utilize your personal data from these services without directly handling it.

How to use iMCP?

1. Download and Install: Download the iMCP app from https://iMCP.app/download (requires macOS 15.3 or later) or install via Homebrew: brew install --cask loopwork/tap/iMCP.
2. Activate Services: After opening the app, an iMCP icon will appear in your menu bar. Click on it to reveal available services. Initially, services are inactive (gray). Click on a service icon (e.g., Calendar, Messages) to activate it. You will be prompted with a macOS permission dialog; grant full access. iMCP does not collect or store your data; clients like Claude Desktop may send data off-device.
3. Connect to Claude Desktop:
   • Download Claude Desktop if you don't have it.
   • In Claude Desktop, go to Settings > Developer > Edit Config.
   • In iMCP, click the menu bar icon > "Configure Claude Desktop" to automatically add or update the MCP server configuration. Alternatively, you can manually copy the server command from iMCP and paste it into the claude_desktop_config.json file under mcpServers.
4. Approve Connection: Quit and reopen Claude Desktop. You will be prompted to approve the connection.
5. Call iMCP tools: Once connected, you will see a hammer icon (🔨) in Claude Desktop, indicating available tools. You can now ask Claude questions that require access to your personal data (e.g., "How's the weather where I am?").

Key Features of iMCP

• MCP Server: Provides an MCP server for macOS services.
• Wide Range of Capabilities:
  • Calendar: View and manage events (create, recurrence, alarms, availability).
  • Contacts: Access and search contacts by name, phone, or email.
  • Location: Access current location data, convert addresses to coordinates.
  • Maps: Place search, directions, POI lookup, travel time, static map generation.
  • Messages: Access message history within customizable date ranges.
  • Reminders: View and create reminders with due dates, priorities, and alerts.
  • Weather: Access current weather conditions for any location.
• Secure Data Access: Leverages Apple's standard security model and permissions, giving users control over data access.
• Privacy-Focused: iMCP itself does not collect or store user data.
• Technical Details:
  • App & CLI: macOS app (iMCP.app) bundles a command-line executable (imcp-server) for MCP server functionality.
  • iMessage Database Access: Includes Madrid, a Swift package for reading and decoding Apple's proprietary typedstream format from the chat.db file.
  • JSON-LD for Tool Results: Tools return results as JSON-LD documents, using Schema.org vocabularies for structured data. Includes Ontology, a Swift package for working with structured data.

Use Cases of iMCP

• AI-Powered Personal Assistant: Integrate AI models like Claude Desktop with your personal data to create a powerful life assistant.
• Automated Information Retrieval: Quickly get answers to questions requiring access to your calendar, contacts, messages, or location.
• Contextual AI Interactions: Enable AI to understand and respond based on your real-world data, such as scheduling events or finding information from your messages.
• Development and Debugging: Use tools like MCP Inspector and Companion to test and debug MCP server interactions.

FAQ from iMCP

• Does iMCP collect or store my data? No, iMCP does not collect or store any of your data. Clients like Claude Desktop, however, may send your data off-device as part of tool calls.
• How do I suggest a new capability? You can reach out to the developers at imcp@loopwork.com.
• What macOS version is required? macOS 15.3 or later.
• How can I debug iMCP interactions? You can use the MCP Inspector (Node.js) or Companion app (macOS 15+) to monitor requests and responses between iMCP and clients.

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

[!TIP] Have a suggestion for a new capability? Reach out to us at imcp@loopwork.com

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 loopwork/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.

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 open the chat.db file through the standard file picker. When you do, macOS adds that file to the app's sandbox. NSOpenPanel is magic like that.

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.

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": "Organization",
  "name": "Loopwork Limited",
  "url": "https://loop.work"
}

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.

Debugging

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 licensed under the Apache License, Version 2.0.

Legal

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