Openai Ocr MCP

🚀 OpenAI OCR MCP Server

An MCP (Model Context Protocol) server that offers Optical Character Recognition (OCR) capabilities, leveraging OpenAI's vision capabilities. This server integrates with Cursor IDE to seamlessly extract text from images.

🚀 Quick Start

The OpenAI OCR MCP Server is designed to work in tandem with Cursor IDE. With this server, you can effortlessly extract text from images and save it as text files.

✨ Features

• Image Text Extraction: Utilize OpenAI's GPT - 4.1 - mini model to extract text from various image formats.
• Automatic Text File Creation: Automatically save the extracted text along with the source image.
• Content - Based File Naming: Organize files using unique content hashes for efficient management.
• Support for Multiple Image Formats: Compatible with JPG, PNG, GIF, and WebP formats.
• Robust Error Handling: Comprehensive validation and error reporting.
• Detailed Logging: Debug - friendly logging for easy troubleshooting.

🔧 Technical Details

Vision Model

• Employ OpenAI's GPT - 4.1 - mini model.
• Optimized for text extraction from images.
• Supports high - detail image analysis.
• Processes images via OpenAI's vision API.

File Handling

• Automatically creates text files.
• Generates content hashes.
• Supports multiple image formats.
• Built on file size validation.

📦 Installation

1. Clone the repository.
2. Install dependencies:

   npm install
   

3. Build the TypeScript code:

   npm run build
   

4. Set the OpenAI API key in the .env file:

   OPENAI_API_KEY=your_api_key_here
   

💻 Usage Examples

In Cursor IDE

1. Configure the MCP server in Cursor settings.
2. Use the OCR tool through Cursor's command panel.
3. Select the image file to process.
4. The extracted text will:
   • Be displayed in Cursor.
   • Be saved as a text file along with the image.

Text File Output

For each processed image, the server creates a text file following this naming convention:

{Original Image Name}-{Content Hash}.txt

Example:

• Input image: document.jpg
• Output file: document-a1b2c3d4.txt

The content_hash is a unique 8 - character hash generated from the extracted text, ensuring:

• Unique file names for different text contents.
• Easy matching between the source image and the extracted text.
• Version tracking when the same image yields different results.

Supported Image Formats

• JPEG/JPG
• PNG
• GIF
• WebP

File Size Limit

• Maximum file size: 5MB.
• Files exceeding this limit will be rejected with an error message.

📚 Documentation

Error Handling

The server provides detailed error messages for common issues:

• Invalid image formats.
• File size exceeding the limit.
• File access problems.
• API key issues.
• Text extraction failures.

Development

Build from Source

npm run build

Run Tests

npm test

Debugging

The server offers detailed logging, including:

• API key validation.
• File processing steps.
• Text extraction results.
• File saving operations.

Environment Variables

• OPENAI_API_KEY: Your OpenAI API key (required).
• Supports standard (sk - ...) and project - specific (sk - proj - ...) API keys.

Contribution

Contributions are welcome! Feel free to submit pull requests.

📄 License

MIT License