# Tesseract OCR MCP 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

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

### 2. Configure Environment

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

```bash
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

```bash
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**
```bash
curl http://localhost:3000/health
```

**2. OCR via File Upload**
```bash
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**
```bash
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**
```bash
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`:

```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`:

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

Then specify the language in your request:
```json
{ "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](https://hub.docker.com/r/jitesoft/tesseract-ocr)
- MCP SDK: [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)