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.

Related MCP server: MokuPDF

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

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

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:

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.