Skip to content
Back to search

MacAppMCPKit

Give your Mac app its own local MCP server, so Claude, VS Code, Codex and other AI assistants on the Mac can read its data

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dbpatel219--macappmcpkit/badge.svg)](/listings/dbpatel219--macappmcpkit)

HTML

<a href="/listings/dbpatel219--macappmcpkit"><img src="/api/listings/dbpatel219--macappmcpkit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 107 lines
  1. # MacAppMCPKit
  2. Let AI assistants on the same Mac — Claude Desktop, Claude Code, VS Code, Codex, Cursor, or anything that
  3. speaks [MCP](https://modelcontextprotocol.io) — read your Mac app's data. Read-only, off until the person
  4. turns it on, and only while your app is open.
  5. You write the tools (Swift closures that return JSON-able values). MacAppMCPKit brings the rest:
  6. - **A server**: MCP over HTTP on `127.0.0.1` only, behind a random key kept in the Keychain.
  7. - **A settings page**: an on/off switch, the assistants with whether each has connected and when it last asked,
  8. one-click setup for Claude Desktop and VS Code, copyable commands for Claude Code and Codex, groups of tools
  9. the person can turn off, and Reset Key.
  10. - **A bridge tool** you embed in the app, for assistants that start MCP servers as programs. It finds your app
  11. on its own, so their setup holds no key or port and never goes stale.
  12. It works in sandboxed apps, including on the Mac App Store. Mergable uses it.
  13. ## Add it to an app
  14. **1. The package.** Add `https://github.com/dbpatel219/MacAppMCPKit` with Swift Package Manager. The app uses
  15. the `MacAppMCPKit` product; the bridge tool (step 4) uses `MacAppMCPBridge`. macOS 13 or later.
  16. **2. Entitlements.** The app needs `com.apple.security.network.server` (it listens on 127.0.0.1), and an
  17. App Group shared with the bridge tool, prefixed with your team ID:
  18. ```xml
  19. <key>com.apple.security.network.server</key>
  20. <true/>
  21. <key>com.apple.security.application-groups</key>
  22. <array><string>TEAMID.com.example.myapp</string></array>
  23. ```
  24. **3. The access object and tools.**
  25. ```swift
  26. import MacAppMCPKit
  27. let access = AssistantAccess(
  28. appName: "My App", serverName: "myapp", defaultPort: 7400,
  29. groups: [ToolGroup(id: "notes", title: "Notes", detail: "Titles and text")],
  30. instructions: "My App keeps notes. These tools read them.",
  31. version: "1.0",
  32. helperName: "myapp-mcp",
  33. desktop: DesktopSetup(appGroup: "TEAMID.com.example.myapp", name: "myapp",
  34. displayName: "My App", author: "Example Inc."))
  35. access.tools = [
  36. MCPTool(name: "search_notes", group: "notes", description: "Notes whose title or text match a query.",
  37. input: ["query": .string("Words to look for", required: true)]) { args in
  38. guard let query = args.string("query") else { throw MCPToolError("Say what to look for.") }
  39. return ["notes": store.search(query).map { ["title": $0.title, "text": $0.text] }]
  40. },
  41. ]
  42. access.startIfEnabled()
  43. ```
  44. Put the settings in your app's settings window:
  45. ```swift
  46. AssistantSettingsSections(access: access, examples: ["What did I write about the launch?"])
  47. ```
  48. **4. The bridge tool.** Add a command-line tool target named after `helperName`, embedded in the app's
  49. `Contents/Helpers`, sandboxed with `com.apple.security.network.client` and the same App Group. (A sandboxed
  50. tool needs a bundle identifier: set `GENERATE_INFOPLIST_FILE` and `CREATE_INFOPLIST_SECTION_IN_BINARY`.)
  51. Its whole `main.swift`:
  52. ```swift
  53. import MacAppMCPBridge
  54. StdioBridge.run(appName: "My App", appGroup: "TEAMID.com.example.myapp", name: "myapp")
  55. ```
  56. Without step 2's App Group and step 4, the settings still offer Claude Code and other apps over HTTP with the key.
  57. ## How it keeps the data on this Mac
  58. - The server listens on `127.0.0.1` only, so other machines can't reach it.
  59. - Every request needs `Authorization: Bearer <key>`, compared in constant time. Reset Key makes a new one.
  60. - Requests from web pages are refused: an `Origin` that isn't this Mac, or a `Host` that isn't `127.0.0.1` or
  61. `localhost` (which stops a site pointing its own domain at 127.0.0.1).
  62. - The server only lists and calls the tools you give it, and marks them read-only.
  63. - The bridge reads the port and key from a file in the App Group container, so no assistant's config file
  64. holds the key.
  65. What an assistant reads goes to whoever runs that assistant; the settings page says so before the person turns
  66. it on. Choose what your tools return with that in mind.
  67. ## How assistants connect
  68. | Assistant | Setup in the settings | How it connects |
  69. | --- | --- | --- |
  70. | Claude Desktop | Add → Claude Desktop asks to install an extension | starts the bridge tool |
  71. | VS Code | Add → VS Code asks to install the server | starts the bridge tool |
  72. | Claude Code | `claude mcp add … -- <bridge> <name>` | starts the bridge tool |
  73. | Codex | `codex mcp add … -- <bridge> <name>` | starts the bridge tool |
  74. | Others (Cursor, Zed, …) | JSON with the address and key | HTTP with the key |
  75. Assistants that run in the cloud (ChatGPT, claude.ai on the web) can't reach a server on the Mac.
  76. ## Status
  77. Young: used in one shipping app. MacAppMCPKit speaks MCP protocol versions 2025-06-18, 2025-03-26 and
  78. 2024-11-05, tools only (no resources, prompts or streaming).
  79. ## License
  80. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.