Freezetext Mcp

FreezeText MCP Server

OCR anything on your Mac screen from Claude, Cursor, or any MCP client.

This is the official Model Context Protocol server for FreezeText — a native macOS app that freezes the screen and extracts text via Apple Vision OCR. Whether running videos, disappearing popups, protected PDFs, or hover tooltips — FreezeText makes any visible text copyable.

You need the FreezeText app installed and running with its HTTP API enabled (Settings → API → “Enable API Server”). This MCP server talks to the app's local API. FreezeText is free to try for 14 days, then a one-time purchase. Get it at store.juergenkoller.software/apps/freezetext.

---

What you can do

"Claude, OCR whatever is on my screen right now and summarize it."

"Cursor, run OCR on this screenshot (base64) and extract the invoice number."

"Search my FreezeText history for everything containing 'tracking number'."

The MCP server exposes 12 tools:

Category	Tools
Capture & OCR	capture_screen (freeze + OCR), capture_region (OCR a specific rect), ocr_image (OCR a base64 image)
History	list_history, search_history, get_history_entry, add_history, delete_history_entry, clear_history, export_history (JSON/CSV)
OCR config	get_ocr_languages, set_ocr_languages

All OCR runs locally via Apple Vision Framework, without a cloud service.

---

Installation

Prerequisites

1. macOS 14 (Sonoma) or later
2. FreezeText app installed and running — get it here (14-day free trial, then a one-time purchase)
3. HTTP API enabled in FreezeText → Settings → API (“Enable API Server”, off by default)
4. Swift 5.9+ (Xcode 15+) if building from source

Build from source

git clone https://github.com/juergenkoller-software/freezetext-mcp.git
cd freezetext-mcp
swift build -c release
# Binary: .build/release/FreezeTextMCP

Pre-built binary

There is no pre-built macOS binary yet; build from source as shown above. The binary attached to Releases is a static Linux x86_64 build for container-based MCP registries such as Glama; it does not run on macOS.

---

Configuration

Claude Desktop

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

{
  "mcpServers": {
    "freezetext": {
      "command": "/path/to/FreezeTextMCP",
      "env": {
        "FREEZETEXT_API_PORT": "9876",
        "FREEZETEXT_API_TOKEN": "your-token-here"
      }
    }
  }
}

FREEZETEXT_API_TOKEN is required: FreezeText answers every request without the right token with HTTP 401. Copy it from FreezeText → Settings → API (“API Token”), or generate one there.

Claude Code

claude mcp add freezetext /path/to/FreezeTextMCP \
  --env FREEZETEXT_API_PORT=9876 \
  --env FREEZETEXT_API_TOKEN=your-token-here

Cursor / other MCP clients

Same pattern — stdio MCP server, configured via the two env vars above.

---

How it works

┌────────────────┐  JSON-RPC stdio   ┌────────────────┐   HTTP(+Bearer)   ┌────────────────┐
│  Claude/Cursor │ ───────────────►  │ FreezeTextMCP  │ ────────────────► │  FreezeText.app│
│  (MCP client)  │ ◄───────────────  │   (this repo)  │ ◄──────────────── │  (port 9876)   │
└────────────────┘                    └────────────────┘                   └────────────────┘

This is a full MCP server (built on the official modelcontextprotocol/swift-sdk) that maps MCP tool calls to FreezeText's local HTTP API. The OCR engine (Apple Vision), screen capture, and history storage live in the FreezeText app.

---

Environment variables

Variable	Default	Description
FREEZETEXT_API_PORT	9876	Port of FreezeText's local HTTP API
FREEZETEXT_API_TOKEN	(none)	Bearer token from FreezeText → Settings → API (required)

---

Errors

Every refusal comes back as an MCP error (isError: true) with a sentence the agent can act on:

Situation	What the bridge reports
FreezeText not running, or API switched off	FreezeText is not reachable at http://localhost:<port>; open FreezeText and turn on “Enable API Server”
Token wrong or missing (HTTP 401)	Set FREEZETEXT_API_TOKEN to the token in FreezeText → Settings → API
No token generated yet (HTTP 503)	Generate one in FreezeText → Settings → API
Any other HTTP error	Status code and FreezeText's error text, e.g. a missing Accessibility permission

Before version 0.2.0 the bridge ignored the HTTP status, so a wrong token looked like a successful call. search_history also never reached the app, because its query string was encoded into the path.

---

About FreezeText

FreezeText is a native macOS OCR utility. Highlights:

• 14-day free trial, then a one-time purchase — no subscription
• Lightning-fast OCR — Apple Vision Framework, under 0.3 seconds
• Freeze the screen — capture text from videos, popups, protected PDFs, hover tooltips
• Global hotkey (⌘⇧7)
• QR code & barcode detection
• Searchable history with color tags + JSON/CSV export
• HTTP API (80+ endpoints) — this MCP server is built on it
• 24 languages
• Local OCR — recognition runs on your Mac, without a cloud service; the licence check needs an internet connection at least every 40 days

→ Get FreezeText at store.juergenkoller.software

---

License

MIT — see LICENSE. This MCP server is open source; the FreezeText app is commercial.

Issues & support

• MCP server bugs: open an issue
• App support: [email protected]

Built by Juergen Koller Software GmbH.