Log inSubmit server
Macos Vision MCP logo

Macos Vision MCP

by woladi

Runs offline OCR, image analysis, and macOS UI inspection through Apple Vision Framework tools.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Macos Vision MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "woladi-macos-vision-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "macos-vision-mcp"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

The install command didn't complete successfully in our automated test.

npx -y macos-vision-mcp

npm notice npm notice New major version of npm available! 10.1.0 -> 12.1.0 npm notice Changelog: <https://github.com/npm/cli/releases/tag/v12.1.0> npm notice Run `npm install -g npm@12.1.0` to update! npm notice npm ERR! code EBADPLATFORM npm ERR! notsup Unsupported platform for macos-vision@1.8.2: wanted {"os":"darwin"} (current: {"os":"linux"}) npm ERR! notsup Valid os: darwin npm ERR! notsup Actual os: linux npm ERR! A complete log of this run can be found in: /home/user/.npm/_logs/2026-0

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 29d ago.

Overview

The woladi/macos-vision-mcp MCP server exposes macOS Vision Framework capabilities to MCP clients for local OCR, image analysis, document inspection, and screen reading. It processes images, PDFs, and screenshots on the Mac, returning text, coordinates, classifications, detections, accessibility data, or pass/fail assertions instead of image bytes. Use it when an agent needs to inspect documents or interact with visible Mac UI without sending files or screenshots to a cloud service. It requires macOS and has no API key requirement.

Use cases

  • Extract text and layout from scanned invoices, contracts, and PDFs
  • Detect barcodes, QR codes, faces, and document boundaries in images
  • Read text from an application's current or occluded window
  • Find UI controls by visible text and verify actions with local assertions
  • Inspect accessibility labels, roles, bounds, colours, and fonts

Key features

  • Offline OCR for images and PDFs
  • Structured paragraphs, text blocks, confidence, and bounding boxes
  • Face, barcode, QR, document-corner, and image classification detection
  • Local screen capture and UI text inspection
  • Accessibility-tree snapshots and text assertions
  • No API key or file upload required

Tools13

What Macos Vision MCP lets your agent do. Expand a tool for its parameters.

Self-reported~460 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

13/14 checks healthy over the last 79d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 9d ago via OSV.dev · macos-vision-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars8Stargazers on the source repository.
npm downloads254Package downloads in the last 30 days.
Last commit2mo agoMost recent push to the default branch.
Install checkInconclusiveInstall command did not finish in our automated test.
Tools exposed13Callable tools this server registers over MCP.
Directory activity8 viewsConfig copies, upvotes, and views on AllMCPs.

How Macos Vision MCP works

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:

Terminal
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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Macos Vision MCP

Run `npx -y macos-vision-mcp` on macOS.

Yes.

No. The server uses macOS Vision Framework locally and does not require an API key.

No. It can find an element and return a click point, but a separate input driver must perform the click.

The repository identifies macOS 13.0 and later as supported.

Related MCP servers

All in Multimedia Process All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMacos Vision MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/woladi-macos-vision-mcp?style=directory)](https://allmcps.com/mcp/woladi-macos-vision-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/woladi-macos-vision-mcp"><img src="https://allmcps.com/api/badge/woladi-macos-vision-mcp?style=directory" alt="Macos Vision MCP on AllMCPs" /></a>