lucid-apple-mcp

MCP server that gives Claude and local LLMs access to Apple's on-device frameworks — Vision OCR, NSDataDetector, and Apple Intelligence FoundationModels. Everything runs on your Mac. Nothing leaves.

Zero tokens consumed · Zero data leaves your Mac.

Tools

| Tool | Engine | Needs Apple Intelligence | Input | Returns | |---|---|---|---|---| | ocr | Vision | No | path | plain text | | recognize_document | Vision | No | path | {transcript, tables} | | detect | NSDataDetector | No | text | JSON array | | extract | FoundationModels | Yes | text, want? | JSON object | | classify | FoundationModels | Yes | text, labels | one label | | summarize | FoundationModels | Yes | text | summary string | | generate | FoundationModels | Yes | prompt, instructions? | reply string |

Three capability tiers:

• ocr + detect — run on any Apple Silicon Mac. No Apple Intelligence, no macOS 26 required.
• recognize_document — requires macOS 26 (Vision's RecognizeDocumentsRequest), but not Apple Intelligence.
• extract, classify, summarize, generate — require macOS 26 + Apple Intelligence enabled in System Settings.

Requirements

• Apple Silicon Mac
• Node.js 18+
• Xcode Command Line Tools (xcode-select --install) — to build the Swift helper
• macOS 26+ — for recognize_document and the four FoundationModels tools
• Apple Intelligence enabled — for extract, classify, summarize, generate only

Install

git clone https://github.com/Lucid-Systems-LLC/Lucid-Apple-MCP.git
cd Lucid-Apple-MCP
npm install        # compiles helper.swift → ./helper automatically (postinstall)

npm install builds the Swift helper for you. On a non-Mac, or a Mac without the Xcode tools, it skips the build with a note instead of failing — run npm run build once the toolchain is present.

Add to Claude Code (CLI)

claude mcp add lucid-apple "$(which node)" "$(pwd)/server.mjs"

$(which node) bakes in the absolute path to your Node binary — which matters (see the note below).

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "lucid-apple": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/lucid-apple-mcp/server.mjs"]
    }
  }
}

Use an absolute path to node — Claude Desktop is launched from the GUI and does not inherit your shell PATH, so a bare "node" fails with spawn node ENOENT (common with nvm or Homebrew). Find yours with which node (e.g. /Users/you/.nvm/versions/node/v20.20.0/bin/node). Use the absolute path to server.mjs too.

Restart Claude Desktop. The tools appear in the MCP panel.

Architecture

Node.js MCP server (server.mjs, stdio transport) spawns a compiled Swift binary (helper) once per tool call — one JSON request on stdin, one JSON result on stdout. The Swift binary bridges:

• Vision (VNRecognizeTextRequest, RecognizeDocumentsRequest) → OCR
• NSDataDetector → deterministic entity detection
• FoundationModels → Apple's on-device LLM

Stateless per call. No persistent process. Safe in air-gap when used with a local LLM client.

Privacy

Computation is fully on-device — files and text never leave the Mac. One honest caveat: when driving this from a cloud assistant (e.g. Claude Desktop), tool results are returned to that assistant and become part of the cloud conversation. For an end-to-end offline pipeline, drive the MCP from a local client like Voical.

Limitations

• recognize_document requires macOS 26; extract, classify, summarize, and generate require macOS 26 with Apple Intelligence enabled. On older macOS these return a clean "requires macOS 26" error — ocr and detect keep working.
• Apple's on-device model is fast and private — not a frontier model. Use it for short answers, drafts, and rewrites.
• ocr and recognize_document require absolute file paths.
• macOS only. No Windows or Linux support.

License

MIT — see LICENSE.

Built by Lucid Systems LLC · Veteran owned · No VC · No cloud