Freezetext Mcp

FreezeText MCP 服务

通过 Claude、Cursor 或任何 MCP 客户端，对 Mac 屏幕上的内容进行 OCR。

这是 FreezeText 的官方 Model Context Protocol 服务——这是一款原生 macOS 应用，可冻结屏幕并通过 Apple Vision OCR 提取文字。无论是正在播放的视频、转瞬即逝的弹窗、受保护的 PDF，还是悬停提示，FreezeText 都能让所有可见文字变得可复制。

你需要安装并运行 FreezeText 应用，并启用其 HTTP API（设置 → API → “Enable API Server”）。此 MCP 服务会与应用的本地 API 通信。FreezeText 可免费试用 14 天，之后需一次性付费购买。请前往 store.juergenkoller.software/apps/freezetext 获取。

---

你可以做什么

“Claude，立即对我屏幕上的内容进行 OCR 并总结。”

“Cursor，对这张截图（base64）运行 OCR，并提取发票号码。”

“在我的 FreezeText 历史记录中搜索所有包含‘tracking number’的内容。”

MCP 服务提供 12 个工具：

类别	工具
捕获与 OCR	capture_screen（冻结屏幕并进行 OCR）、capture_region（对指定矩形区域进行 OCR）、ocr_image（对 base64 图像进行 OCR）
历史记录	list_history、search_history、get_history_entry、add_history、delete_history_entry、clear_history、export_history（JSON/CSV）
OCR 配置	get_ocr_languages、set_ocr_languages

所有 OCR 都通过 Apple Vision Framework 在本地运行，无需云服务。

---

安装

前置条件

1. macOS 14（Sonoma）或更高版本
2. 已安装并运行 FreezeText 应用——点击此处获取（可免费试用 14 天，之后需一次性付费购买）
3. 在 FreezeText → 设置 → API 中启用 HTTP API（“Enable API Server”，默认关闭）
4. Swift 5.9+（Xcode 15+），用于从源代码构建

从源代码构建

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

预构建二进制文件

目前尚无预构建的 macOS 二进制文件；请按照上述说明从源代码构建。Releases 中附带的二进制文件是为 Glama 等基于容器的 MCP 注册表提供的静态 Linux x86_64 构建版本，无法在 macOS 上运行。

---

配置

Claude Desktop

编辑 ~/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 为必填项：如果令牌不正确，FreezeText 会对每个请求返回 HTTP 401。请从 FreezeText → Settings → API（“API Token”）复制令牌，或在此处生成一个。

Claude Code

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

Cursor / 其他 MCP 客户端

使用相同的配置方式——通过上述两个环境变量配置 stdio MCP 服务。

---

工作原理

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

这是一个完整的 MCP 服务（基于官方 modelcontextprotocol/swift-sdk 构建），可将 MCP 工具调用映射到 FreezeText 的本地 HTTP API。OCR 引擎（Apple Vision）、屏幕捕获和历史记录存储均由 FreezeText 应用负责。

环境变量

变量	默认值	描述
FREEZETEXT_API_PORT	9876	FreezeText 本地 HTTP API 的端口
FREEZETEXT_API_TOKEN	(none)	来自 FreezeText → Settings → API 的 Bearer 令牌（必需）

---

错误

每次拒绝操作都会作为 MCP 错误（isError: true）返回，并附带一句可供 Agent 采取行动的说明：

情况	桥接报告的内容
FreezeText 未运行，或 API 已关闭	无法通过 http://localhost:<port> 访问 FreezeText；请打开 FreezeText 并启用“Enable API Server”
令牌错误或缺失（HTTP 401）	将 FREEZETEXT_API_TOKEN 设置为 FreezeText → Settings → API 中的令牌
尚未生成令牌（HTTP 503）	在 FreezeText → Settings → API 中生成令牌
任何其他 HTTP 错误	状态码和 FreezeText 的错误文本，例如缺少辅助功能权限

在 0.2.0 版本之前，桥接会忽略 HTTP 状态码，因此错误的令牌看起来像是调用成功了。search_history 也从未传到应用，因为它的查询字符串被编码进了路径。

---

关于 FreezeText

FreezeText 是一款原生 macOS OCR 工具。主要特色：

• 14 天免费试用，之后一次性购买——无需订阅
• 闪电般快速的 OCR——Apple Vision Framework，耗时不到 0.3 秒
• 冻结屏幕——从视频、弹窗、受保护的 PDF、悬停提示中捕获文本
• 全局快捷键（⌘⇧7）
• 二维码和条形码检测
• 可搜索的历史记录，支持颜色标签和 JSON/CSV 导出
• HTTP API（80 多个端点）——此 MCP 服务基于它构建
• 24 种语言
• 本地 OCR——识别在 Mac 上运行，无需云服务；许可证检查至少每 40 天需要联网一次

→ 在 store.juergenkoller.software 获取 FreezeText

---

许可证

MIT——详见 LICENSE。此 MCP 服务为开源项目；FreezeText 应用为商业软件。

问题与支持

• MCP 服务错误：提交问题
• 应用支持：[email protected]

由 Juergen Koller Software GmbH 构建。