# woladi/macos-vision-mcp [Health: Active]

**Category:** 🎥 Multimedia Process  
**Repository:** https://github.com/woladi/macos-vision-mcp  
**GitHub Stars:** 6  
**npm Downloads (last month):** 2100  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/woladi-macos-vision-mcp

## Description
Local OCR and image analysis via Apple Vision Framework. Wraps macOS's native Vision API to expose OCR for images and PDFs (with reading-order paragraphs, bounding boxes, line/paragraph IDs, and confidence), face / barcode / QR / document-corner detection, and image classification — all as MCP tools any client (Claude Code, Claude Desktop, Cursor, Codex CLI) can call. 97% token savings vs sending raw images. Fully offline, no API keys, files never leave the Mac. One-line install: npx -y macos-vision-mcp.

## Tools
Capabilities this server exposes over MCP:

- **ocr_image** — Extract text from an image or PDF (JPG, PNG, HEIC, TIFF, PDF). Returns plain text, or per-page paragraphs + text blocks with `lineId` / `paragraphId` and bounding boxes. Accepts `start_page` / `max_pages` for partial PDF OCR.
- **detect_faces** — Detect human faces and return their count and positions.
- **detect_barcodes** — Read QR codes, EAN, UPC, Code128, PDF417, Aztec, and other 1D/2D codes.
- **detect_document** — Detect the four corner points of a document in a photo (paper, receipt, ID). Useful as a crop / deskew hint before OCR.
- **classify_image** — Classify image content into 1000+ categories with confidence scores.
- **analyze_document** — Returns structured JSON with reading-order paragraphs, raw text blocks (bbox / confidence), faces, barcodes, and rectangles — ready for the model to reconstruct into Markdown, HTML, or anything else. Also accepts `start_page` / `max_pages` for long PDFs.
- **capture_screen** — Screenshot the main display, a window (even occluded), an app's frontmost window, or a region. Returns the file path + screen-point frame — never the image bytes.
- **list_windows** — List on-screen windows with global screen-point bounds, front-to-back.
- **read_screen_text** — Capture + OCR in one step — read what an app shows right now, fully offline.
- **find_element** — Find a UI element by visible text; returns `clickPoint {x,y}` in global screen points (exact → substring → fuzzy matching with near-miss reporting).
- **assert_text** — Local pass/fail assertion that text is present on / absent from the screen — the verdict is computed on your Mac, not by a cloud model.
- **vision_capabilities** — Report macOS version, Screen Recording / Accessibility permission state, and displays.
- **ui_snapshot** — Return the whole layout as JSON: every element's exact box, role, label and state from the accessibility tree, optionally with colours and fonts — plus visible text the tree does not account for.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "macos-vision-mcp": {
    "command": "npx",
    "args": ["-y","macos-vision-mcp"]
  }
}
```

## Documentation

## What woladi/macos-vision-mcp MCP server does

The woladi/macos-vision-mcp MCP server provides local document OCR, image analysis, and macOS UI inspection through MCP tools. It uses Apple Vision Framework capabilities to process JPG, PNG, HEIC, TIFF, and PDF files on the Mac. OCR results can include reading-order paragraphs, text blocks, line and paragraph identifiers, bounding boxes, and confidence values. PDF analysis supports selecting a starting page and limiting the number of pages processed.

The server also detects faces, reads barcodes and QR codes, identifies document corners, and classifies images into more than 1,000 categories with confidence scores. `analyze_document` combines document text, layout data, face detections, barcode results, and rectangle information into structured JSON that an agent can use to produce Markdown, HTML, DOCX, or another format.

For Mac UI work, tools can list windows, capture the main display, capture a window or region, read visible text, locate controls by their displayed text, and verify whether text is present or absent. `ui_snapshot` exposes accessibility-tree information such as element bounds, roles, labels, and states, with optional colour and font data. The server reports click coordinates but does not perform clicks itself.

## How it works

The woladi/macos-vision-mcp MCP server runs locally and invokes macOS Vision and screen-access capabilities. Images and documents remain on the Mac during processing. MCP clients receive extracted text, structured JSON, geometry, classifications, or assertion results; the tools do not return image bytes. This makes the server suitable for reducing the amount of document or screen content passed to a model, although the stated token reduction is an example rather than a guaranteed result for every file.

A typical UI workflow is to list windows, locate an element by visible text, pass the returned `clickPoint` to a separate input automation tool, and then use `assert_text` to check the result. Matching supports exact, substring, and fuzzy approaches, with near-miss reporting. Screen capture can target an occluded window or an application's frontmost window without requiring the agent to interpret a remote screenshot.

## Setup and configuration

Install the published package with:

```bash
npx -y macos-vision-mcp
```

The README identifies macOS 13.0 or later as the supported platform. The server is designed to work offline after installation and does not require an API key. Screen and accessibility features depend on the corresponding macOS permissions; `vision_capabilities` can report Screen Recording and Accessibility permission state, the macOS version, and connected displays.

## Tools and capabilities

- Extract OCR text and structured layout data from images and PDFs.
- Process selected PDF page ranges with `start_page` and `max_pages`.
- Detect faces, barcodes, QR codes, document corners, and image categories.
- Capture screens, windows, application windows, and regions while returning file paths and screen coordinates.
- Read screen text locally and find visible UI elements with click coordinates.
- Assert screen text locally and inspect accessibility-tree structure with `ui_snapshot`.

## Limitations and notes

The woladi/macos-vision-mcp MCP server is macOS-specific and depends on Apple Vision Framework functionality. It reports where an element can be clicked but does not control the pointer or keyboard, so a separate input driver is needed for actions. Screen and accessibility operations may not work until macOS grants the required permissions.

The server returns structured representations rather than screenshot image bytes. Agents that need visual details not captured by OCR or accessibility data may therefore need another approach. Processing is local, but the resulting extracted text and JSON can still be sent onward by the MCP client to its model provider.

_Full upstream README: https://allmcps.com/mcp/woladi-macos-vision-mcp/readme_