A local OpenCV pipeline that finds the page, straightens it, removes shadows and whitens the paper, then bundles your photos into one 300 DPI PDF. Plus the setup to let AI agents call the CamScanner MCP endpoint.
Independent open-source project. Not affiliated with CamScanner / INTSIG.
Detect the page
Straighten it
De-shadow and whiten
Export a PDF page
Looping animation of the scan pipeline: detect, straighten, de-shadow and whiten, export.
5 stagesdetect, light map, shadow division, tone curve, sharpen
300 DPImulti-page PDF written with Pillow, JPEG quality 95
~3.2 sfor 20 high-res pages, as reported in the README
0 uploadsthe local engine makes no network calls
Features
Everything a phone-photo scanner should do, on your machine
Two engines in one repo: a free local Python pipeline for bulk scanning, and ready-made configuration for the remote CamScanner MCP endpoint.
No watermark added
The PDFs the local engine writes contain only your pages. No "Scanned with..." footer, no logo, no stamp.
Magic Color filter
A custom OpenCV filter isolates non-uniform shadow fields, estimates the illumination and turns dull gray paper into pure white (#FFFFFF) while keeping vivid ink colours.
Automatic perspective fix
Canny edge detection and contour approximation find the page on a desk or table and warp skewed camera angles flat.
MCP native
Connects Claude Desktop, Kilo CLI, Cursor and any MCP client to the remote Streamable HTTP endpoint at ai-tools.camscanner.com/mcp.
Fast and offline
Runs on your own CPU with no cloud round trip. The README reports about 3.2 seconds for 20 high-resolution pages.
Multi-page batch to one PDF
Reads JPG, PNG or WebP photos from a folder, orders them by filename and bundles them into a single 300 DPI PDF.
How it works
Five stages from crooked photo to flat white page
Every number below comes straight from scripts/batch_scanner.py. For the full derivations see the Algorithm Deep Dive.
1
Detect and rectify
Shrink to 1000 px, blur, run Canny, close gaps, keep the largest four-corner outline (over 40% of the frame) and warp it flat.
Canny 30 / 120
2
Estimate the light
Dilate with an 11x11 window to erase ink, then median-filter at 31x31. What is left is the lighting on blank paper.
dilate 11, median 31
3
Divide out shadows
Scale every colour channel by 255 / background. Shadows and gradients cancel, inks keep their hue.
pixel x 255 / bg
4
Magic Color curve
Values from 215 up become pure white, ink under 40 is deepened, midtones are stretched.
215 to #FFFFFF
5
Sharpen and export
A 3x3 unsharp kernel crisps the strokes, then Pillow saves one multi-page PDF.
JPEG q95, 300 DPI
The Magic Color tone curve
A 256-entry lookup table. Ink below 40 scales by 0.75, 40 to 215 stretches onto 30 to 255, and anything 215 or brighter becomes pure white.
Why shadows disappear
Paper brightness is lighting times reflectance. Divide by an estimate of the lighting and the shadow cancels.
The sharpening kernel
A 3x3 unsharp filter applied last. The weights sum to 1.0, so overall brightness does not shift; only edges get crisper.
0-0.30-0.32.2-0.30-0.30
Then Pillow saves every page into one PDF with quality=95 and dpi=(300, 300).
The MCP angle
Let your AI agent call the scanner
The README describes the CamScanner MCP as an official remote Model Context Protocol endpoint over Streamable HTTP. It lets agents like Claude and Kilo trigger OCR, PDF merging, document translation and format conversion through tool calls. This repo shows how to wire it up, and keeps a free local engine beside it.
Add it to your MCP client
Snippets copied from the README. Endpoint: https://ai-tools.camscanner.com/mcp
Sign-in and Cursor setup. The repo's MCP Integration Guide covers the OAuth 2.0 sign-in, Cursor and VS Code configuration, and the camscanner-cli commands. The remote endpoint is CamScanner's own service, so its terms and any account or quota limits apply.
Local engine or remote MCP?
Summarised from the guide's comparison. Use whichever fits, or both.
Local Python engine
Remote CamScanner MCP
Runs on
Your CPU (OpenCV, NumPy, Pillow)
CamScanner's hosted service
Network
None needed; photos stay on your machine
Internet and sign-in; documents travel to the cloud
Does
Edge detection, perspective fix, shadow removal, Magic Color, multi-page PDF
OCR, PDF merging, translation, format conversion (README); table extraction and search (guide)
OCR
Not included
Yes
Cost
Free, MIT
Needs a CamScanner account; the guide notes a Pro plan or API quota may apply
Best for
Bulk offline digitising of photo dumps
Letting agents read, transcribe and search documents
Use both
The guide's suggested workflow: scan locally first, then hand the finished PDF to the remote OCR.
both engines, from the MCP guide
# Step 1: Process local camera captures using Python
python scripts/batch_scanner.py "path/to/raw_photos""output/Scanned_Document_HD.pdf"# Step 2: Use CamScanner remote OCR via CLI or Agent
camscanner-cli image ocr --input "output/Scanned_Document_HD.pdf" --format markdown --output "output/Document_Transcript.md"
Quick start
From clone to PDF in two commands
Commands are copied from the README. You need Python 3.9 or newer.
1Install
terminal
# Clone the repository
git clone https://github.com/MHJoy99/camscanner-mcp-hd-scanner.git
cd camscanner-mcp-hd-scanner
# Install Python requirements
pip install opencv-python pillow numpy pypdf
# (Optional) Install official CamScanner CLI
npm install -g camscanner-cli
Finds the page contour and removes the table edges.
Estimates ambient light and eliminates shadows.
Applies the Magic Color tone curve.
Sharpens with an unsharp kernel.
Exports a 300 DPI multi-page PDF with no watermark.
Good to know. Pass both arguments to batch_scanner.py. A lighter script, scan_to_pdf.py, processes the images sitting next to it and writes Scanned_HD_Output.pdf; run it as python scan_to_pdf.py bw for a black-and-white filter (default is magic_color). Both are read from the repo's code, not the README.
FAQ
Questions people ask
Answers are taken from the README, the docs folder and the code.
What is CamScanner MCP & HD Auto-Scanner?
It is an open-source (MIT) Python project with two engines. A local OpenCV pipeline turns phone photos of paper into clean multi-page PDFs: it finds the page, flattens the perspective, estimates and removes shadows, whitens the paper and sharpens the ink. The repo also documents how to connect AI agents such as Claude Desktop, Kilo CLI and Cursor to the CamScanner MCP endpoint. It is an independent project and is not affiliated with CamScanner or INTSIG.
How do I scan phone photos to a PDF without a watermark?
Put your photos in a folder (JPG, PNG or WebP; the script also reads JPEG and BMP) and run python scripts/batch_scanner.py "path/to/raw_photos" "output/Scanned_Document_HD.pdf". The script processes the images in filename order, applies the Magic Color pipeline to each one and writes a single multi-page PDF. The local engine adds no stamp or watermark to the PDF it writes.
Does it work offline? Are my documents uploaded?
The local engine runs entirely on your machine with OpenCV, NumPy and Pillow, and its code makes no network calls, so your photos are not uploaded. The remote CamScanner MCP endpoint is different: the integration guide notes that it needs internet access and a sign-in, and that documents sent to it travel to CamScanner's cloud.
How does the shadow removal and paper whitening work?
It estimates the lighting first: a grayscale copy is dilated with an 11x11 kernel, which erases thin ink strokes, then smoothed with a 31x31 median filter. Each colour channel is then multiplied by 255 divided by that background estimate, which cancels uneven light and cast shadows. A tone curve maps values of 215 and above to pure white and deepens dark ink, and a 3x3 sharpening kernel finishes the page.
How do I connect it to Claude Desktop, Cursor or Kilo CLI?
Add the CamScanner MCP endpoint, https://ai-tools.camscanner.com/mcp, to your client's MCP configuration. The README shows a Kilo CLI snippet (type remote, with an X-IS-AGENT: general header) and a Claude Desktop snippet. The MCP Integration Guide in the repo also covers Cursor and VS Code, the OAuth 2.0 sign-in and the camscanner-cli commands.
What can the CamScanner MCP endpoint do?
According to the README it is a remote Model Context Protocol endpoint using Streamable HTTP that lets AI agents trigger OCR, PDF merging, document translation and format conversion through tool calls. The integration guide also lists table extraction and document search. These tools run on CamScanner's servers, not in this repo's Python engine.
Is there a page or resolution limit?
The README states there is no page cap and that the PDF is written at 300 DPI. In the code, every image found in the folder is processed and held in memory, then saved as one PDF with JPEG quality 95 and 300 DPI metadata, so very large batches are bounded by your available memory rather than by a built-in limit.
How fast is it?
The README reports about 3.2 seconds for 20 high-resolution pages on a CPU, and the Algorithm Deep Dive reports about 153 ms for one 12-megapixel page on its test machine. These are the author's own figures and will vary with your hardware.
Which situations does it handle poorly?
Page detection looks for a four-corner outline covering at least 40% of the frame. If it finds a different outline it falls back to a bounding box, and if it finds none it trims a 2.5% border. White paper on a white desk is hard for edge detection, and the scripts do not flatten curved book pages or correct glossy reflections, because a plain perspective warp assumes a flat sheet.
Is it affiliated with CamScanner? What licence is it under?
No. This is an independent project by MHJoy99 and is not affiliated with CamScanner or INTSIG. The README calls its filter "CamScanner Magic Color"; the repo reproduces a similar look with OpenCV, and CamScanner remains a trademark of its owner. The code is MIT licensed, free for personal, educational and commercial use.