macOS OCR MCP Tool

This project provides a MetaCall Protocol (MCP) tool to perform Optical Character Recognition (OCR) on images using macOS’s built-in Vision framework. It exposes an ocr_image tool that takes an image file path and returns the recognized text along with confidence scores and bounding boxes.

Project Setup

Dependencies

This project relies on Python 3.13+ and the following main dependencies:

• ocrmac: For accessing macOS OCR capabilities. See ocrmac.
• Pillow: For image manipulation.
• mcp[cli]>=1.7.1: For the MetaCall Protocol server and client.

Installation

It is recommended to use a virtual environment.

1. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate
   

2. Install dependencies using uv:

   uv sync
   

Running the MCP Server

To start the MCP server, run main.py:

uv run main.py

This will start the MCP server, making the ocr_image tool available.

Available MCP Tools

ocr_image

• Description: Conducts OCR on the provided image file using macOS’s built-in capabilities. Returns recognized text segments, their confidence scores, and bounding box coordinates.
• Input: file_path: str - The absolute or relative path to the image file.
• Output (Example Success):

  {
    "filename": "path/to/your/image.png",
    "annotations": [
      {
        "text": "Hello World",
        "confidence": 0.95,
        "bounding_box": [0.1, 0.1, 0.5, 0.05] 
      },
      // ... more annotations
    ]
  }
  

• Output (Example Error):

  {
    "error": "OCR functionality is only available on macOS."
  }
  

  or

  {
    "error": "File not found: path/to/nonexistent/image.png"
  }
  

Note: This tool will only function correctly on a macOS system due to its reliance on the Vision framework.

Testing with MCP Inspector

You can use the MCP Inspector to connect to the running MCP server and test the tool.

Cursor MCP Configuration

To configure this MCP server in Cursor, you can add the following to your MCP JSON configuration file (e.g., ~/.cursor/mcp.json or project-specific .cursor/mcp.json):

{
  "mcpServers": {
    "ocrmac": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/macos-ocr-mcp",
        "run",
        "main.py"
      ]
    }
  }
}

This configuration tells Cursor how to start your MCP server. You can then call the ocrmac.ocr_image tool from within Cursor.