mdshrink
Auto-compress PDFs and screenshots to Markdown before they hit Claude Code's context. 5-10x fewer tokens, fully local, one-line install.
What is mdshrink?
mdshrink is an MCP server that automatically converts PDFs and screenshots to compact Markdown before they hit Claude Code's context window. It preserves semantic content while reducing token usage by 5-10x.
Why?
When you attach a PDF or screenshot in Claude Code:
- A typical 20-page PDF consumes 25k-40k tokens
- A single screenshot consumes 1.5k-3k tokens per image
Most of those tokens are visual redundancy - fonts, layout, whitespace - that the model doesn't need. mdshrink extracts the semantic content and discards the bloat.
Installation
pip install mdshrink-mcp
claude mcp add mdshrink -- mdshrink
Restart Claude Code. That's it.
Usage
Once installed, Claude Code will automatically call mdshrink tools before reading PDF or image files:
compress_pdf- Converts PDFs to compact Markdowncompress_image- OCR extracts text from screenshotsget_compressed- Cache lookup (fast check)
Each conversion reports:
original_tokens- Estimated tokens for native filecompressed_tokens- Actual tokens in Markdownratio- Compression ratio (e.g., "5.2x")
What It Compresses Well
| Type | Compression | Notes |
|---|---|---|
| Text-native PDFs | 5-10x | API specs, RFCs, papers, contracts |
| Screenshots of text | 3-5x | Code, error messages, docs, terminal |
| Scanned docs | Varies | Requires OCR (future) |
What It Doesn't Compress
- Scanned/image-only PDFs (v1.1+)
- Tables with complex merged cells
- Equations and charts
- Photos where visual IS the content
- Diagrams (v1.2+ with VLM)
Troubleshooting
Tool not triggering?
/mcp
Should show:
✔ Found 1 MCP server
• mdshrink: connected (3 tools)
If not, reinstall:
claude mcp remove mdshrink
claude mcp add mdshrink -- mdshrink
Permission errors on Windows
Run PowerShell as Administrator, then:
pip install --force-reinstall mdshrink-mcp
Cache location
- Linux/macOS:
~/.cache/mdshrink/ - Windows:
%LOCALAPPDATA%\mdshrink\
Disable caching: MDSHRINK_NO_CACHE=1
Clear cache:
from mdshrink_mcp import cache
cache.clear_cache()
Uninstall
claude mcp remove mdshrink
pip uninstall mdshrink-mcp
License
MIT - See LICENSE for details.
Credits
1 maintainer
Metadata
1 maintainer
Release files for mdshrink-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mdshrink_mcp-0.1.0.tar.gz | 10.2 kB | Without provenance | Details for mdshrink_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mdshrink_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for mdshrink_mcp-0.1.0-py3-none-any.whl |
Total release size: 20.3 kB
Release files / mdshrink_mcp-0.1.0.tar.gz
| Download URL | mdshrink_mcp-0.1.0.tar.gz |
|---|---|
| Size | 10.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
da86c96a41a252f6e3926d9d52e7d249eff88f9e30231d63bc9169320605e08e
|
|
BLAKE2b-256 checksum How to use checksums |
6933ee3758f057bfd5b5da6a3c3567c5e3d9502d97fb54afe8b54df89b35845d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.11
|
Release files / mdshrink_mcp-0.1.0-py3-none-any.whl
| Download URL | mdshrink_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 10.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bd7a38d8bba722bc2ff21856c55e6ebd53621590cfa1c95f27d1cc984fc9e03a
|
|
BLAKE2b-256 checksum How to use checksums |
ca9e71adaddcf79dc8969c9f12a5207227f7d942e65847e2d005b39fc1ab5a75
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.11
|
Security for mdshrink-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
