lucid-apple-mcp

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