Gemini OCR

Provides OCR capabilities powered by Gemini, exposing image-to-text endpoints for file and base64 inputs via an MCP server.

python

4

GitHub Stars

python

Language

5 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "windoc-gemini-ocr-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/project/gemini-ocr-mcp",
        "run",
        "gemini-ocr-mcp.py"
      ],
      "env": {
        "GEMINI_MODEL": "gemini-2.5-flash-preview-05-20",
        "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

You can run a Gemini-powered OCR service as an MCP server to extract text from images. It supports taking an image file or a base64-encoded image, returning the plain text result. This makes it easy to integrate OCR into your MCP workflow or automation.

How to use

Use the Gemini OCR MCP server from an MCP client by invoking its OCR tools. You can process a local image file or a base64-encoded image string. The server returns the extracted plain text for further processing or storage in your workflow.

How to install

Prerequisites: you need Python 3.8 or higher and a Google Gemini API key.

Clone the project directory.
Create and activate a virtual environment.
Install the required dependencies using the UV tool.

# Clone the repository
git clone https://github.com/WindoC/gemini-ocr-mcp
cd gemini-ocr-mcp

# Create and activate a virtual environment (example for Unix-like systems)
# Install uv standalone if needed
curl -LsSf https://astral.sh/uv/install.sh | sh

Configuration and run details

You run this as an MCP server under UV, with a Python script responsible for the OCR service. The configuration shown below demonstrates how to wire the server into a parent MCP application. Replace the placeholder paths and API key with your actual values.

{
  "mcpServers": {
    "gemini-ocr-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "x:\\path\\to\\your\\project\\gemini-ocr-mcp",
        "run",
        "gemini-ocr-mcp.py"
      ],
      "env": {
        "GEMINI_MODEL": "gemini-2.5-flash-preview-05-20",
        "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

Run and test as a server

With the configuration in place, start the MCP server through your parent MCP application so the gemini-ocr-mcp service becomes available to other MCP clients. Ensure your GEMINI_API_KEY is valid and the chosen GEMINI_MODEL is supported by your project.

Additional notes

Two OCR functions are exposed by the server. Use the functions from your MCP client to obtain text from either a file or a base64 string.

ocr_image_file: input image_file (path to the image). Returns the extracted text as a string.
ocr_image_base64: input base64_image (base64 encoded string). Returns the extracted text as a string.

Security and keys

Keep your Gemini API key secure. Do not commit keys to source control. Use environment variable management or secret storage in your deployment environment.

Available tools

ocr_image_file

Performs OCR on a local image file. Input is an image_file path; returns the extracted text.

ocr_image_base64

Performs OCR on a base64 encoded image. Input is a base64_image string; returns the extracted text.