carrot-mcp-pdf
Carrot MCP PDF Server — convert PDFs to structured markdown or rendered page images.
Installation
uv sync --all-packages
Usage
# Run as MCP server
uv run carrot-mcp-pdf
# Or via main CLI
uv run carrot-mcp pdf
# Or as Python module
uv run python -m carrot_mcp_pdf
Tools
| Tool | Description |
|---|---|
version |
Get server version info |
get_toc |
Get table of contents with page ranges |
get_pages |
Convert specific pages to markdown or rendered images. Accepts pages as int (single page), str (range like '1-5,8,10-12'), list, or None. Returns list[TextContent | ImageContent] |
grep |
Search for exact substring in PDF pages. Case-insensitive by default, or regex. Returns matches with page number, text, and surrounding context. |
Architecture
Application Layer (server.py — MCP tools, thin routing)
↓ get_toc/get_pages
Conversion Layer (converter.py — pymupdf4llm → markdown + images)
↓ extract_text=False → render_page_as_image
Cache Layer (cache.py — JSON: %APPDATA%/carrot-mcp/pdf/<md5>.json)
-
server.py — MCP tool definitions only, delegates to converter/cache
-
converter.py — PDF conversion, image processing, content parsing
-
cache.py — Cache persistence, path management, parse_page_range
-
Cache:
%APPDATA%/carrot-mcp/pdf/<md5>.json -
Content blocks: each page caches ordered blocks
[{type: "text", data: ...}, {type: "image", data: base64_str, mime: ...}] -
Image return: images returned as MCP
ImageContentattachments (no base64 truncation)
Development
# Run tests
uv run pytest tests/pdf/ -v
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file carrot_mcp_pdf-0.2.4.tar.gz.
File metadata
- Download URL: carrot_mcp_pdf-0.2.4.tar.gz
- Upload date:
- Size: 6.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ca47c9e8eb7b1bc4ccb52649a5b2b6cb7b6792d6bd5e82014f8e20f78c07d0c8
|
|
| MD5 |
19be799b1e245ce570f5a0dfc76d9e6f
|
|
| BLAKE2b-256 |
562b5e4ee0912ba549fa4e67703a88c487f8edc2a6f453604df289e60c8dd573
|
File details
Details for the file carrot_mcp_pdf-0.2.4-py3-none-any.whl.
File metadata
- Download URL: carrot_mcp_pdf-0.2.4-py3-none-any.whl
- Upload date:
- Size: 8.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
01c2dcab4ac10fca4256f93e714326f730c82d77b630678519224ab5a200ebf4
|
|
| MD5 |
80a4415f2a0ca70b61990c236ff2c3ea
|
|
| BLAKE2b-256 |
78a82efb5b4707461a0edd8320f57cc76bc161e0bbf7c601db30e19b20e7f8b8
|
