OCR MCP

MCP server che converte screenshot di pagine web in Markdown strutturato usando GLM-OCR (Zhipu). Si registra nel mcp-gateway: i tool compaiono in Claude come mcp__mcp-gateway__ocr__*.

Tool

Tool	Cosa fa
ocr_image(image, instructions="")	OCR di un'immagine già catturata. image = base64, data URI, o URL http(s) a un'immagine.
ocr_webpage(url, full_page=True, viewport_width=0, wait_until="networkidle", instructions="")	Cattura uno screenshot full-page dell'URL con Chromium headless, poi OCR.
ocr_health()	Stato e configurazione (host GLM-OCR, API style, modello, key, Chromium, tiling). Nessuna chiamata a pagamento.

I tool restituiscono il Markdown come testo. Il server NON scrive file .md: gira su un LXC remoto senza accesso al disco locale. È la sessione Claude a salvare il .md dove serve (es. "salva il risultato in ./pagina.md").

Motore OCR — .env

Il server è agnostico all'endpoint: si passa da cloud a self-hosted cambiando solo il .env.

Variabile	Cloud Zhipu	vLLM self-hosted
GLM_OCR_BASE_URL	https://api.z.ai/api/paas/v4	http://<host-vllm>:8000
GLM_OCR_API_STYLE	layout_parsing	chat
GLM_OCR_MODEL	glm-ocr	zai-org/GLM-OCR
GLM_OCR_API_KEY	chiave API Zhipu	token del server vLLM

• chat → POST {BASE}/v1/chat/completions (OpenAI-compatibile).
• layout_parsing → POST {BASE}/layout_parsing (endpoint dedicato Zhipu).

Screenshot molto alti: tagliati in tile sovrapposte (MAX_TILE_HEIGHT / TILE_OVERLAP / MAX_TILES) e il Markdown viene ricucito automaticamente.

Deploy (CT102)

./deploy/install.sh root@192.168.1.107

rsync → /opt/ocr-mcp, crea venv, playwright install --with-deps chromium, installa e avvia il servizio systemd ocr-mcp. Poi su CT102 compila /opt/ocr-mcp/.env e systemctl restart ocr-mcp.

Registrazione nel gateway

Su CT102, aggiungere alla lista upstreams: in /etc/mcp-gateway/upstreams.yaml:

- name: ocr
  url: http://127.0.0.1:8011/sse
  tags:
  - core
  - ocr

poi systemctl restart mcp-gateway.

Porta 8011: la 8009 è occupata da gmail e la 8008 da un altro servizio. Se va cambiata, aggiornare config.py, .env, deploy/ocr-mcp.service e la voce upstreams.yaml. Il tag core rende i tool visibili nelle sessioni che caricano il set core del gateway.

Verifica

• curl http://127.0.0.1:8011/ → 200 con stato.
• In Claude Code /mcp → mcp__mcp-gateway__ocr__ocr_image | ocr_webpage | ocr_health.
• Chiamare ocr_health, poi ocr_webpage su una pagina lunga reale.

Stack

Python 3.12 · FastMCP (mcp==1.27.0) · Uvicorn · httpx · Playwright/Chromium · Pillow. Transport SSE su /sse, servizio systemd, log di audit dei job in SQLite (/var/lib/ocr-mcp/ocr_mcp.db).