Tesseract OCR Server

A lightweight, containerized Model Context Protocol (MCP) server and HTTP API for Tesseract OCR. Built on Alpine Linux, it allows AI assistants (like Claude Desktop, Cursor, or Windsurf) and standard applications to perform Optical Character Recognition via stdin/stdout streams or REST API endpoints.

🚀 Features

• Dual Mode Operation: Run as an MCP server (stdin/stdout) for AI integration, an HTTP REST API, or both simultaneously.
• Lightweight: Based on jitesoft/tesseract-ocr:alpine (~43MB base).
• Secure: Optional API Key authentication for HTTP endpoints.
• Flexible Input: Accepts file uploads, base64 encoded strings, or file paths.
• Configurable: Control ports, host, languages, and modes via environment variables.
• Auto-Cleanup: Temporary files are automatically managed and deleted after processing.

📋 Prerequisites

• Docker & Docker Compose
• Portainer or Dockhand (optional, for GUI management)
• An MCP Client (e.g., Claude Desktop, Cursor IDE) if using MCP mode

🛠️ Installation & Deployment

1. Clone the Repository

git clone <your-repo-url>
cd tesseract-mcp-server

2. Configure Environment

Copy the example environment file and edit it to suit your needs:

cp .env.example .env
nano .env

Key Configuration Options:

Variable	Default	Description
MCP_ENABLED	true	Enable MCP stdio protocol (for AI assistants).
HTTP_ENABLED	true	Enable HTTP REST API.
PORT	3000	Port for the HTTP server.
HOST	0.0.0.0	Host interface to bind to.
API_KEY	``	Recommended. Set a secret key to protect HTTP endpoints.
DEFAULT_LANGUAGE	eng	Default OCR language code (e.g., eng, fra, deu).
MAX_FILE_SIZE	10485760	Max upload size in bytes (default 10MB).

3. Deploy with Docker Compose

docker-compose up -d --build

4. Deploy via Portainer / Dockhand

1. Go to Stacks > Add Stack.
2. Paste the contents of docker-compose.yml.
3. In the Environment Variables section, add your desired config (see .env.example).
4. Click Deploy.

---

🔌 Usage Modes

Mode 1: HTTP API (REST)

If HTTP_ENABLED=true, the server exposes REST endpoints.

🔐 Authentication

If API_KEY is set in your environment, you must include it in every request via:

• Header: x-api-key: YOUR_API_KEY
• Query Param: ?api_key=YOUR_API_KEY

Endpoints

1. Health Check

curl http://localhost:3000/health

2. OCR via File Upload

curl -X POST http://localhost:3000/ocr \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image=@path/to/image.png" \
  -F "language=eng" \
  -F "output_format=text"

3. OCR via Base64

curl -X POST http://localhost:3000/ocr/base64 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_data": "iVBORw0KGgoAAAANSUhEUg...",
    "language": "eng",
    "output_format": "text"
  }'

4. Get Configuration

curl http://localhost:3000/config \
  -H "x-api-key: YOUR_API_KEY"

---

Mode 2: MCP Server (AI Integration)

If MCP_ENABLED=true, the server listens on stdin/stdout. This is designed to be connected to AI clients like Claude Desktop or Cursor.

Setup for Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "tesseract-ocr": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "MCP_ENABLED=true",
        "-e",
        "HTTP_ENABLED=false",
        "your-image-name:latest"
      ]
    }
  }
}

Note: Ensure the image is built locally or available in your registry.

Available MCP Tools

1. ocr_image: Process an image from a path or base64 string.
2. ocr_from_stdin: Process raw base64 image data.
3. get_config: Retrieve current server configuration.

---

🌍 Supported Languages

Tesseract supports many languages. You must install the specific language packs in the Docker image if you need more than English.

To add languages, modify the Dockerfile.mcp:

RUN apk add --no-cache tesseract-ocr-fra tesseract-ocr-deu

Then specify the language in your request:

{ "language": "fra" } // French

Common codes: eng (English), spa (Spanish), fra (French), deu (German), chi_sim (Chinese Simplified).

---

🏗️ Project Structure

.
├── docker-compose.yml    # Deployment configuration
├── Dockerfile.mcp        # Image build instructions
├── package.json          # Node.js dependencies
├── server.js             # Main application logic (MCP + HTTP)
├── .env.example          # Example environment variables
└── README.md             # This file

---

🔒 Security Best Practices

1. Always set an API_KEY in production environments when exposing HTTP ports.
2. Restrict HOST: If running locally, set HOST=127.0.0.1 to prevent external access.
3. Limit File Size: Adjust MAX_FILE_SIZE to prevent denial-of-service via large uploads.
4. Read-Only Volumes: If mounting volumes for input, mount them as read-only (:ro) where possible.

---

🐛 Troubleshooting

Q: The container starts but exits immediately. A: Check logs with docker logs tesseract-mcp-server. Ensure MCP_ENABLED or HTTP_ENABLED is set to true. If both are false, the server has nothing to do.

Q: I get "Unauthorized" errors. A: You have set an API_KEY in your environment but are not sending it in the request headers or query parameters.

Q: OCR accuracy is low. A: Try preprocessing the image (increasing contrast, resizing) before sending it. You can also experiment with the psm (Page Segmentation Mode) parameter in the MCP tool arguments.

---

📄 License

MIT License. Feel free to use and modify.

🙏 Credits

• Base Image: jitesoft/tesseract-ocr
• MCP SDK: @modelcontextprotocol/sdk