{"id":26116941,"url":"https://github.com/loopwork-ai/imcp","last_synced_at":"2025-04-10T02:18:58.294Z","repository":{"id":281011828,"uuid":"943286066","full_name":"loopwork-ai/iMCP","owner":"loopwork-ai","description":"A macOS app that provides an MCP server to your Messages, Contacts, and more","archived":false,"fork":false,"pushed_at":"2025-03-31T13:58:49.000Z","size":1778,"stargazers_count":324,"open_issues_count":10,"forks_count":10,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-31T14:22:58.560Z","etag":null,"topics":["macos","mcp"],"latest_commit_sha":null,"homepage":"https://iMCP.app/download","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/loopwork-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-05T13:14:00.000Z","updated_at":"2025-03-31T13:58:52.000Z","dependencies_parsed_at":"2025-03-21T20:22:12.633Z","dependency_job_id":"92f76d49-63c2-4081-b7f2-be20ce35c9f8","html_url":"https://github.com/loopwork-ai/iMCP","commit_stats":null,"previous_names":["loopwork-ai/imcp"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopwork-ai%2FiMCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopwork-ai%2FiMCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopwork-ai%2FiMCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopwork-ai%2FiMCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loopwork-ai","download_url":"https://codeload.github.com/loopwork-ai/iMCP/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248142906,"owners_count":21054672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["macos","mcp"],"created_at":"2025-03-10T10:53:21.995Z","updated_at":"2025-04-10T02:18:58.260Z","avatar_url":"https://github.com/loopwork-ai.png","language":"Swift","readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"Assets/hero-dark.svg\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"Assets/hero-light.svg\"\u003e\n  \u003cimg alt=\"iMCP\"\u003e\n\u003c/picture\u003e\n\niMCP is a macOS app for connecting your digital life with AI.\nIt works with [Claude Desktop][claude-app]\nand a [growing list of clients][mcp-clients] that support the\n[Model Context Protocol (MCP)][mcp].\n\n## Capabilities\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003e\n      \u003cimg src=\"Assets/calendar.svg\" width=\"48\" height=\"48\" alt=\"\" role=\"presentation\"/\u003e\n    \u003c/th\u003e\n    \u003ctd\u003e\u003cstrong\u003eCalendar\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003eView and manage calendar events, including creating new events with customizable settings like recurrence, alarms, and availability status.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003cth\u003e\n      \u003cimg src=\"Assets/contacts.svg\" width=\"48\" height=\"48\" alt=\"\" role=\"presentation\"/\u003e\n    \u003c/th\u003e\n    \u003ctd\u003e\u003cstrong\u003eContacts\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003eAccess contact information about yourself and search your contacts by name, phone number, or email address.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003cth\u003e\n      \u003cimg src=\"Assets/location.svg\" width=\"48\" height=\"48\" alt=\"\" role=\"presentation\"/\u003e\n    \u003c/th\u003e\n    \u003ctd\u003e\u003cstrong\u003eLocation\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003eAccess current location data and convert between addresses and geographic coordinates.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003cth\u003e\n      \u003cimg src=\"Assets/messages.svg\" width=\"48\" height=\"48\" alt=\"\" role=\"presentation\"/\u003e\n    \u003c/th\u003e\n    \u003ctd\u003e\u003cstrong\u003eMessages\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003eAccess message history with specific participants within customizable date ranges.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003cth\u003e\n      \u003cimg src=\"Assets/reminders.svg\" width=\"48\" height=\"48\" alt=\"\" role=\"presentation\"/\u003e\n    \u003c/th\u003e\n    \u003ctd\u003e\u003cstrong\u003eReminders\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003eView and create reminders with customizable due dates, priorities, and alerts across different reminder lists.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003cth\u003e\n      \u003cimg src=\"Assets/weather.svg\" width=\"48\" height=\"48\" alt=\"\" role=\"presentation\"/\u003e\n    \u003c/th\u003e\n    \u003ctd\u003e\u003cstrong\u003eWeather\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003eAccess current weather conditions including temperature, wind speed, and weather conditions for any location.\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003e [!TIP]\n\u003e Have a suggestion for a new capability?\n\u003e Reach out to us at \u003cimcp@loopwork.com\u003e\n\n## Getting Started\n\n### Download and open the app\n\nFirst, [download the iMCP app](https://iMCP.app/download)\n(requires macOS 15.3 or later).\n\n\u003cimg align=\"right\" width=\"344\" src=\"/Assets/imcp-screenshot-first-launch.png\" alt=\"Screenshot of iMCP on first launch\" /\u003e\n\nWhen you open the app,\nyou'll see a\n\u003cimg style=\"display: inline\" width=\"20\" height=\"16\" src=\"/Assets/icon.svg\" /\u003e\nicon in your menu bar.\n\nClicking on this icon reveals the iMCP menu,\nwhich displays all available services.\nInitially, all services will appear in gray,\nindicating they're inactive.\n\nThe blue toggle switch at the top indicates that the MCP server is running\nand ready to connect with MCP-compatible clients.\n\n\u003cbr clear=\"all\"\u003e\n\n\u003cimg align=\"right\" width=\"372\" src=\"/Assets/imcp-screenshot-grant-permission.png\" alt=\"Screenshot of macOS permission dialog\" /\u003e\n\n### Activate services\n\nTo activate a service, click on its icon.\nThe system will prompt you with a permission dialog.\nFor example, when activating Calendar access, you'll see a dialog asking `\"iMCP\" Would Like Full Access to Your Calendar`.\nClick \u003ckbd\u003eAllow Full Access\u003c/kbd\u003e to continue.\n\n\u003e [!IMPORTANT]\n\u003e iMCP **does not** collect or store any of your data.\n\u003e Clients like Claude Desktop _do_ send\n\u003e your data off device as part of tool calls.\n\n\u003cbr clear=\"all\"\u003e\n\n\u003cimg align=\"right\" width=\"344\" src=\"/Assets/imcp-screenshot-all-services-active.png\" alt=\"Screenshot of iMCP with all services enabled\" /\u003e\n\nOnce activated,\neach service icons goes from gray to their distinctive colors —\nred for Calendar, green for Messages, blue for Location, and so on.\n\nRepeat this process for all of the capabilities you'd like to enable.\nThese permissions follow Apple's standard security model,\ngiving you complete control over what information iMCP can access.\n\n\u003c!-- \u003cbr clear=\"all\"\u003e --\u003e\n\n\u003c!-- \u003cimg align=\"right\" width=\"344\" src=\"/Assets/imcp-screenshot-configure-claude-desktop.png\" /\u003e --\u003e\n\n\u003cbr clear=\"all\"\u003e\n\n### Connect to Claude Desktop\n\nIf you don't have Claude Desktop installed,\nyou can [download it here](https://claude.ai/download).\n\nOpen Claude Desktop and go to \"Settings... (\u003ckbd\u003e⌘\u003c/kbd\u003e\u003ckbd\u003e,\u003c/kbd\u003e)\".\nClick on \"Developer\" in the sidebar of the Settings pane,\nand then click on \"Edit Config\".\nThis will create a configuration file at\n`~/Library/Application Support/Claude/claude_desktop_config.json`.\n\n\u003cbr/\u003e\n\nTo connect iMCP to Claude Desktop,\nclick \u003cimg style=\"display: inline\" width=\"20\" height=\"16\" src=\"/Assets/icon.svg\" /\u003e\n\\\u003e \"Configure Claude Desktop\".\n\nThis will add or update the MCP server configuration to use the\n`imcp-server` executable bundled in the application.\nOther MCP server configurations in the file will be preserved.\n\n\u003cdetails\u003e\n\u003csummary\u003eYou can also configure Claude Desktop manually\u003c/summary\u003e\n\nClick \u003cimg style=\"display: inline\" width=\"20\" height=\"16\" src=\"/Assets/icon.svg\" /\u003e\n\\\u003e \"Copy server command to clipboard\".\nThen open `claude_desktop_config.json` in your editor\nand enter the following:\n\n```json\n{\n  \"mcpServers\" : {\n    \"iMCP\" : {\n      \"command\" : \"{paste iMCP server command}\"\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cimg align=\"right\" width=\"372\" src=\"/Assets/imcp-screenshot-approve-connection.png\" /\u003e\n\n### Call iMCP tools from Claude Desktop\n\nQuit and reopen the Claude Desktop app.\nYou'll be prompted to approve the connection.\n\n\u003e [!NOTE]\n\u003e You may see this dialog twice;\n\u003e click approve both times.\n\n\u003cbr clear=\"all\"\u003e\n\nAfter approving the connection,\nyou should now see 🔨12 in the bottom right corner of your chat box.\nClick on that to see a list of all the tools made available to Claude\nby iMCP.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"694\" src=\"/Assets/claude-desktop-screenshot-tools-enabled.png\" alt=\"Screenshot of Claude Desktop with tools enabled\" /\u003e\n\u003c/p\u003e\n\nNow you can ask Claude questions that require access to your personal data,\nsuch as:\n\u003e \"How's the weather where I am?\"\n\nClaude will use the appropriate tools to retrieve this information,\nproviding you with accurate, personalized responses\nwithout requiring you to manually share this data during your conversation.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"738\" src=\"/Assets/claude-desktop-screenshot-message.png\" alt=\"Screenshot of Claude response to user message 'How's the weather where I am?'\" /\u003e\n\u003c/p\u003e\n\n## Technical Details\n\n### App \u0026 CLI\n\niMCP is a macOS app that bundles a command-line executable, `imcp-server`.\n* [`iMCP.app`](/App/) provides UI for configuring services and — most importantly —\n  a means of interacting with macOS system permissions,\n  so that it can access Contacts, Calendar, and other information.\n* [`imcp-server`](/CLI/) provides an MCP server that \n  uses standard input/output for communication \n  ([stdio transport][mcp-transports]).\n\nThe app and CLI communicate with each other on the local network\nusing [Bonjour][bonjour] for automatic discovery. \nBoth advertise a service with type \"_mcp._tcp\" and domain \"local\".\nRequests from MCP clients are read by the CLI from `stdin`\nand relayed to the app;\nresponses from the app are received by the CLI and written to `stdout`.\nSee [`StdioProxy`](https://github.com/loopwork-ai/iMCP/blob/8cf9d250286288b06bf5d3dda78f5905ad0d7729/CLI/main.swift#L47) \nfor implementation details.\n\nFor this project, we created [mcp-swift-sdk]:\na Swift SDK for Model Context Protocol servers and clients.\nThe app uses this package to handle proxied requests from MCP clients.\n\n### iMessage Database Access\n\nApple doesn't provide public APIs for accessing your messages.\nHowever, the Messages app on macOS stores data in a SQLite database located at\n`~/Library/Messages/chat.db`.\n\niMCP runs in [App Sandbox][app-sandbox],\nwhich limits its access to user data and system resources.\nWhen you go to enable the Messages service,\nyou'll be prompted to open the `chat.db` file through the standard file picker.\nWhen you do, macOS adds that file to the app’s sandbox.\n[`NSOpenPanel`][nsopenpanel] is magic like that.\n\nBut opening the iMessage database is just half the battle.\nOver the past few years, \nApple has moved away from storing messages in plain text\nand instead toward a proprietary `typedstream` format.\n\nFor this project, we created [Madrid][madrid]:\na Swift package for reading your iMessage database.\nIt includes a Swift implementation for decoding Apple's `typedstream` format, \nadapted from Christopher Sardegna's [imessage-exporter] project \nand [blog post about reverse-engineering `typedstream`][typedstream-blog-post].\n\n### JSON-LD for Tool Results\n\nThe tools provided by iMCP return results as\n[JSON-LD][json-ld] documents.\nFor example,\nthe `fetchContacts` tool uses the [Contacts framework][contacts-framework],\nwhich represents people and organizations with the [`CNContact`][cncontact] type.\nHere's how an object of that type is encoded as JSON-LD:\n\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Organization\",\n  \"name\": \"Loopwork Limited\",\n  \"url\": \"https://loop.work\"\n}\n```\n\n[Schema.org][schema.org] provides standard vocabularies for\npeople, postal addresses, events, and many other objects we want to represent.\nAnd JSON-LD is a convenient encoding format for \nhumans, AI, and conventional software alike.\n\nFor this project, we created [Ontology][ontology]:\na Swift package for working with structured data.\nIt includes convenience initializers for types from Apple frameworks, \nsuch as those returned by iMCP tools.\n\n## Acknowledgments\n\n- [Justin Spahr-Summers](https://jspahrsummers.com/)\n  ([@jspahrsummers](https://github.com/jspahrsummers)),\n  David Soria Parra\n  ([@dsp-ant](https://github.com/dsp-ant)), and\n  Ashwin Bhat\n  ([@ashwin-ant](https://github.com/ashwin-ant))\n  for their work on MCP.\n- [Christopher Sardegna](https://chrissardegna.com)\n  ([@ReagentX](https://github.com/ReagentX))\n  for reverse-engineering the `typedstream` format\n  used by the Messages app.\n\n## License\n\nThis project is licensed under the Apache License, Version 2.0.\n\n## Legal\n\niMessage® is a registered trademark of Apple Inc.  \nThis project is not affiliated with, endorsed, or sponsored by Apple Inc.\n\n[app-sandbox]: https://developer.apple.com/documentation/security/app-sandbox\n[bonjour]: https://developer.apple.com/bonjour/\n[claude-app]: https://claude.ai/download\n[contacts-framework]: https://developer.apple.com/documentation/contacts\n[cncontact]: https://developer.apple.com/documentation/contacts/cncontact\n[imessage-exporter]: https://github.com/ReagentX/imessage-exporter\n[json-ld]: https://json-ld.org\n[madrid]: https://github.com/loopwork-ai/Madrid\n[mcp]: https://modelcontextprotocol.io/introduction\n[mcp-clients]: https://modelcontextprotocol.io/clients\n[mcp-transports]: https://modelcontextprotocol.io/docs/concepts/architecture#transport-layer\n[nsopenpanel]: https://developer.apple.com/documentation/appkit/nsopenpanel\n[ontology]: https://github.com/loopwork-ai/Ontology\n[schema.org]: https://schema.org\n[mcp-swift-sdk]: https://github.com/loopwork-ai/mcp-swift-sdk\n[typedstream-blog-post]: https://chrissardegna.com/blog/reverse-engineering-apples-typedstream-format/","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floopwork-ai%2Fimcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floopwork-ai%2Fimcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floopwork-ai%2Fimcp/lists"}