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 ```bash 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) ```bash 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`: ```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](LICENSE). --- Built by [Lucid Systems LLC](https://lucidsystemsai.com) · Veteran owned · No VC · No cloud