PDFCompress

PDFCompress is an open-source, structure-preserving PDF compressor for humans and AI agents. It uses independently verified WPS-style image presets, but does not call or distribute WPS DLLs and does not depend on a WPS account.

Its core rule is simple:

Keep text and vectors as text and vectors; downsample only oversized painted images; verify the result before publishing it.

Features

• Computes image resolution from the actual PDF transformation matrix, including images nested in Form XObjects.
• Applies WPS-compatible high, standard, medium, and low settings.
• Adds an archive-safe profile for award, tender and archival attachments.
• Preserves the source file and writes atomically to a different output path.
• Preserves bookmarks, attachments, annotations, fonts and visible PDF structure by default.
• Refuses signed PDFs unless signature invalidation is explicitly accepted.
• Verifies page count, page boxes and extractable text after every candidate.
• Supports a target size without repeatedly recompressing the previous JPEG result.
• Provides a Python API, CLI, shared Agent Skill, Codex plugin, Claude Code plugin, and MCP server.

Installation

Python 3.11 or newer is required.

git clone https://github.com/ncepuee/PDFCompress.git
cd PDFCompress
python -m pip install -e ".[mcp]"

With uv:

uv tool install --editable ".[mcp]"

Install the tagged GitHub release without cloning:

uv tool install "pdfcompress-agent[mcp] @ git+https://github.com/ncepuee/PDFCompress.git@v0.1.0"

Quick start

Analyze before compressing:

pdfcompress analyze "input.pdf" --json

Compress using the WPS-compatible high-quality profile:

pdfcompress compress "input.pdf" "output.pdf" --preset high --json

For a formal attachment that must be under 4 MB:

pdfcompress compress "input.pdf" "output.pdf" `
  --preset archive-safe `
  --target-size-mb 4 `
  --json

Verify an existing pair:

pdfcompress verify "input.pdf" "output.pdf" --json

Presets

Preset	Trigger PPI	Target PPI	JPEG quality	Intended use
archive-safe	360	300	85	Conservative formal and archival attachments
high	300	300	75	WPS-compatible high quality
standard	150	150	75	WPS-compatible standard quality
medium	110	110	50	WPS-compatible medium quality
low	96	96	30	WPS-compatible low quality

The four WPS-compatible values were recovered from the installed compression plugin's generateCompressArgs branches and independently documented in the companion analysis note. The exact WPS resampling kernel, chroma subsampling policy and complete optimizer bitmask are not copied or claimed.

Target-size behavior

When --target-size-mb is supplied, PDFCompress tries progressively stronger profiles starting at the requested preset. Every attempt reopens the original PDF:

archive-safe → high → standard → medium → low

The first verified candidate under the limit is selected. If no profile reaches the limit, the smallest verified candidate is returned with a warning. PDFCompress does not silently rasterize pages, delete fonts, or remove attachments to force the target.

Agent integration

Claude Code

Install the Python package first, then load the plugin for a session:

cd PDFCompress
claude --plugin-dir .

Invoke the skill as /pdfcompress:pdf-compress, or ask Claude to compress a PDF. Claude Code also loads the plugin's .mcp.json and starts pdfcompress-mcp over stdio.

Codex

The repository contains a validated .codex-plugin/plugin.json, a shared skills/ directory and .mcp.json. It can be installed from a local Codex marketplace, or the skill can be copied to a personal/project skill directory. The core package must be installed so pdfcompress-mcp is on PATH.

Generic MCP clients

Use this stdio configuration:

{
  "mcpServers": {
    "pdfcompress": {
      "type": "stdio",
      "command": "pdfcompress-mcp",
      "args": []
    }
  }
}

MCP tools:

• analyze_pdf(path, password?)
• compress_pdf(input_path, output_path, preset?, target_size_mb?, overwrite?, allow_signature_loss?)
• verify_pdf(input_path, output_path)

Open-source research and adopted ideas

Project	Strength	What PDFCompress adopts
qpdf	Mature content-preserving PDF transformations and repair	Reliable parsing, object-stream writing and structural preservation through pikepdf
pikepdf	Python API over qpdf	Core object model, image decoding, resource cleanup and save pipeline
pdfcpu	Standalone batch CLI and broad validation commands	Script-friendly subcommands and JSON reports
OCRmyPDF	Safe staged processing and PDF/A-aware workflows	Temporary candidates, final verification and atomic publishing
Ghostscript	Effective image downsampling controls	Separate trigger PPI, target PPI and quality presets; not bundled because of license boundary
MuPDF	Multi-level garbage collection and duplicate stream reuse	Aggressive cleanup is treated as a separate, testable stage; not bundled
pdfsizeopt	Multi-stage smallest-file optimization	Compare candidates and select the smallest verified output

See THIRD_PARTY_NOTICES.md for license boundaries.

Safety and limitations

• Rewriting a PDF invalidates digital signatures. The default is to stop.
• Encrypted PDFs require a password; encryption is preserved on output.
• Version 0.1 skips image masks, transparency, custom decode arrays, unusual color spaces and non-8-bit images instead of risking visual corruption.
• Text equality checks use extractable text. Scanned pages without OCR still require visual QA.
• Pixel-level render comparison is recommended before using the tool on legally significant or highly complex documents.
• If a candidate is not smaller than the source, PDFCompress outputs a byte-for-byte source copy and reports that no safe size reduction was found.

Validated example

On a 12-page, image-heavy PDF used during development:

Profile	Source	Output	Reduction	Verification
archive-safe	24,004,483 B	3,149,368 B	86.88%	Pages, boxes and extracted text equal
high	24,004,483 B	2,940,952 B	87.75%	Pages, boxes and extracted text equal

At 100 DPI render comparison, all page dimensions matched; the archive-safe result had a mean per-page RGB RMS difference of 0.388 and a maximum of 3.002 on a 0–255 channel scale. This is one validation case, not a universal quality guarantee.

Development

python -m pip install -e ".[mcp,dev]"
pytest
ruff check .

Tests generate their own PDF containing searchable text and a high-resolution image. No private documents are included in the repository.

License

PDFCompress is released under the MIT License. Third-party dependencies retain their own licenses.

See the changelog and GitHub releases for versioned changes and downloadable Python packages.