oxidize-pdf

PyPI version CI License: MIT Python Typed MCP

oxidize-python MCP server

Rust-powered PDF library for Python. Generate, parse, split, merge, and manipulate PDFs with native performance. Ships with a built-in MCP server so AI agents can work with PDFs out of the box.

No C dependencies. No Java. No subprocess calls.

Installation

pip install oxidize-pdf            # Core library
pip install "oxidize-pdf[mcp]"     # + MCP server for AI agents

Platforms: Linux (x86_64, aarch64) | macOS (x86_64, Apple Silicon) | Windows (x86_64) Requires: Python 3.10+

Why oxidize-pdf?

oxidize-pdf Pure-Python libs C/Java wrappers
Performance Native (compiled Rust) Interpreted Native but heavy
Dependencies Zero Varies Poppler, Java, Ghostscript
Memory safety Rust ownership model GC-dependent Manual / GC
Type stubs Full (mypy/pyright) Partial Rare
AI-ready (MCP) Built-in No No

MCP Server

Give your AI agent full PDF capabilities in one line:

oxidize-mcp

The built-in Model Context Protocol server exposes 12 tools, 6 resources, and 5 prompts — compatible with Claude, GPT, and any MCP client.

Claude Desktop integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "oxidize-pdf": {
      "command": "oxidize-mcp",
      "env": {
        "OXIDIZE_WORKSPACE": "/path/to/your/pdfs"
      }
    }
  }
}

GitHub Copilot (VS Code) integration

Copilot's agent mode speaks MCP. Add .vscode/mcp.json to your workspace:

{
  "servers": {
    "oxidize-pdf": {
      "command": "oxidize-mcp",
      "env": {
        "OXIDIZE_WORKSPACE": "/path/to/your/pdfs"
      }
    }
  }
}

Open the Chat view, switch to Agent mode, and the 12 PDF tools appear in the tool picker. (The same block also works under the mcp.servers key in your user settings.json if you prefer a global install.)

OpenAI Agents SDK integration

The OpenAI Agents SDK spawns the server over stdio and exposes its tools to an agent:

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    params={"command": "oxidize-mcp", "env": {"OXIDIZE_WORKSPACE": "/path/to/your/pdfs"}},
    cache_tools_list=True,
) as server:
    agent = Agent(
        name="PDF assistant",
        instructions="Use the oxidize-pdf tools to inspect and manipulate PDFs.",
        mcp_servers=[server],
    )
    result = await Runner.run(agent, "How many pages does report.pdf have?")
    print(result.final_output)

A runnable version is in examples/openai_agents_quickstart.py.

Both integrations run the server locally over stdio, so its tools operate on PDFs in the configured workspace directory. Remote/hosted use (e.g. the OpenAI Responses API hosted MCP tool) needs an HTTP transport and is not yet exposed.

Available tools

Tool What it does
read_pdf Read metadata — page count, version, encryption status, title, author
extract_text Extract text from all pages or a specific page
convert_pdf Convert to markdown, chunks, or RAG-optimized format
create_pdf Create a new PDF with optional metadata
save_pdf Save a session to disk, with optional encryption
add_content Add pages, text, and graphics to a session
annotate_pdf Add text annotations and highlights
manipulate_pdf Split, merge, rotate, extract pages, reverse, overlay
manage_forms Create, fill, read, and validate form fields
secure_pdf Encrypt, check permissions, verify signatures
extract_entities Extract structured entities from pages
analyze_pdf Validate structure, detect corruption, check PDF/A compliance

The server also exposes resources (session data, capabilities, version info) and prompts (guided workflows for summarization, data extraction, form filling, and more).

Configuration

OXIDIZE_WORKSPACE=/path/to/pdfs oxidize-mcp

The server is configured entirely through environment variables:

Variable Default Purpose
OXIDIZE_WORKSPACE ~/Documents/oxidize-mcp Sandbox root; all paths must resolve inside it.
OXIDIZE_ALLOWED_PATHS (none) Comma-separated extra directories allowed outside the workspace.
OXIDIZE_MAX_FILE_SIZE_MB 100 Reject input PDFs larger than this on disk.
OXIDIZE_MAX_PAGES 10000 Reject documents with more pages than this before any extraction work.
OXIDIZE_MAX_OUTPUT_BYTES 10485760 Cap the serialized size of a tool's JSON response (10 MB).
OXIDIZE_MAX_SESSIONS 10 Maximum concurrent stateful PDF-creation sessions.
OXIDIZE_MAX_SESSION_BYTES 10485760 Cap the content a single session may accumulate (10 MB).
OXIDIZE_SESSION_TIMEOUT 3600 Session expiry, in seconds.

Resource caps (OXIDIZE_MAX_*) protect the server from a large or malicious PDF: oversized documents are rejected up front and tool responses are bounded rather than serialized unbounded. Exceeding a cap returns an error with code RESOURCE_LIMIT.

Or start programmatically:

from oxidize_pdf.mcp.server import run
run()

Python API

Create a PDF

from oxidize_pdf import Document, Page, Font, Color

doc = Document()
doc.set_title("My Document")
doc.set_author("Jane Doe")

page = Page.a4()
page.set_font(Font.HELVETICA, 24.0)
page.set_text_color(Color.black())
page.text_at(72.0, 750.0, "Hello from oxidize-pdf!")

page.set_font(Font.TIMES_ROMAN, 12.0)
page.text_at(72.0, 700.0, "Generated with Python + Rust.")

doc.add_page(page)
doc.save("output.pdf")

Parse an existing PDF

from oxidize_pdf import PdfReader

reader = PdfReader.open("document.pdf")
print(f"Pages: {reader.page_count}, Version: {reader.version}")

for i, text in enumerate(reader.extract_text()):
    print(f"--- Page {i + 1} ---")
    print(text)

Operations

from oxidize_pdf import split_pdf, merge_pdfs, rotate_pdf, extract_pages

split_pdf("input.pdf", "output_dir/")                       # Split into individual pages
merge_pdfs(["part1.pdf", "part2.pdf"], "merged.pdf")         # Merge multiple PDFs
rotate_pdf("input.pdf", "rotated.pdf", 90)                   # Rotate all pages
extract_pages("input.pdf", "subset.pdf", [0, 2, 4])          # Extract specific pages

Graphics

from oxidize_pdf import Document, Page, Color

doc = Document()
page = Page.a4()

page.set_fill_color(Color.hex("#3498db"))
page.draw_rect(72.0, 700.0, 200.0, 100.0)
page.fill()

page.set_stroke_color(Color.red())
page.set_line_width(2.0)
page.draw_circle(300.0, 500.0, 50.0)
page.stroke()

doc.add_page(page)
doc.save("graphics.pdf")

Types

from oxidize_pdf import Color, Point, Rectangle, Margins, Font

# Colors
Color.rgb(1.0, 0.0, 0.0)          # RGB
Color.hex("#ff6600")               # Hex
Color.cmyk(0.0, 1.0, 1.0, 0.0)   # CMYK

# Geometry
Point(72.0, 720.0)
Rectangle.from_xywh(72.0, 72.0, 468.0, 648.0)
Margins.uniform(72.0)

# Fonts — all 14 standard PDF fonts
Font.HELVETICA    # Font.HELVETICA_BOLD
Font.TIMES_ROMAN  # Font.TIMES_BOLD
Font.COURIER      # Font.COURIER_BOLD

Error handling

from oxidize_pdf import PdfReader, PdfError, PdfIoError, PdfParseError

try:
    reader = PdfReader.open("missing.pdf")
except PdfIoError as e:
    print(f"I/O error: {e}")
except PdfParseError as e:
    print(f"Parse error: {e}")
except PdfError as e:
    print(f"PDF error: {e}")

Exception hierarchy: PdfError > PdfIoError, PdfParseError, PdfEncryptionError, PdfPermissionError

MCP Server

oxidize-pdf includes an MCP server that exposes PDF capabilities to AI assistants like Claude. Install with the mcp extra:

pip install oxidize-pdf[mcp]

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "oxidize-pdf": {
      "command": "uvx",
      "args": ["--from", "oxidize-pdf[mcp]", "oxidize-mcp"]
    }
  }
}

Claude Code

claude mcp add oxidize-pdf -- uvx --from "oxidize-pdf[mcp]" oxidize-mcp

Available tools

Tool Description
read_pdf Open a PDF and get metadata (pages, version, encryption)
extract_text Extract text content from PDF pages
convert_pdf Convert between PDF versions
analyze_pdf Analyze structure, fonts, images, and compliance
extract_entities Extract images and digital signatures
manipulate_pdf Split, merge, rotate, extract, and reorder pages
annotate_pdf Add text annotations, highlights, and stamps
manage_forms Create, fill, and read PDF form fields
secure_pdf Encrypt, decrypt, and set document permissions
create_pdf Create a new PDF document with pages
add_pdf_content Add text, shapes, and images to pages
save_pdf Save the document to file or bytes

Resources

  • oxidize://fonts — Available built-in PDF fonts
  • oxidize://page-sizes — Standard page sizes with dimensions
  • oxidize://capabilities — Server capabilities and tool listing
  • oxidize://version — Version information
  • oxidize://workspace — PDF files in the workspace directory
  • oxidize://session/{id} — Session data by ID

Known limitations

  • Encryption write support: Document.encrypt() configures encryption parameters but the underlying Rust library does not yet serialize the encryption dictionary to the PDF output. Reading encrypted PDFs works correctly.
  • CPython only: PyPy and GraalPy are not supported.

License

MIT — see LICENSE for details.

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.16.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for bytaro from gravatar.com bytaro

Credits

Author: Santiago Fernández Muñoz

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License

Requires

Python >=3.10

Provides Extra

dev mcp

Tags

pdf pdf-generation pdf-parser pdf-merge rust

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

oxidize_pdf-0.14.0.tar.gz (655.6 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

oxidize_pdf-0.14.0-cp310-abi3-win_amd64.whl (5.0 MB view details)

Uploaded CPython 3.10+Windows x86-64

oxidize_pdf-0.14.0-cp310-abi3-manylinux_2_28_x86_64.whl (5.7 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ x86-64

oxidize_pdf-0.14.0-cp310-abi3-manylinux_2_28_aarch64.whl (5.7 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ ARM64

oxidize_pdf-0.14.0-cp310-abi3-macosx_11_0_arm64.whl (5.3 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

oxidize_pdf-0.14.0-cp310-abi3-macosx_10_12_x86_64.whl (5.6 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file oxidize_pdf-0.14.0.tar.gz.

File metadata

  • Download URL: oxidize_pdf-0.14.0.tar.gz
  • Upload date:
  • Size: 655.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for oxidize_pdf-0.14.0.tar.gz
Algorithm Hash digest
SHA256 fefb200eae482b024c7d2506c7f2db0465e90da0c6a15111c082e492d99d5a6a
MD5 0b9338ef00ef7a8ed87810b988088221
BLAKE2b-256 e8ae70da91483e482b072e31901888025fc93e5d04e3d59d6c124a91b16d880e

See more details on using hashes here.

Provenance

The following attestation bundles were made for oxidize_pdf-0.14.0.tar.gz:

Publisher: release.yml on bzsanti/oxidize-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oxidize_pdf-0.14.0-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: oxidize_pdf-0.14.0-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 5.0 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for oxidize_pdf-0.14.0-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 55158b6e2ce1008390d965f81a0e479ccc791ed12ddfd9dcddc3189a1bc196c1
MD5 dd563eb79462a840c62966ed31c3117e
BLAKE2b-256 e088df13e03cce59aac6837f904b4817f725e4262b5614666eb3e114c4ea5bdf

See more details on using hashes here.

Provenance

The following attestation bundles were made for oxidize_pdf-0.14.0-cp310-abi3-win_amd64.whl:

Publisher: release.yml on bzsanti/oxidize-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oxidize_pdf-0.14.0-cp310-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for oxidize_pdf-0.14.0-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 455092beed4b35e99b95897e5e05456cb0ac81625bd9d2860110d9bdeb722b23
MD5 df6b076a9c9d4272d06a62aaec06d8f6
BLAKE2b-256 248953ab5d81e026ecce0f019343c75679e2ee7f79661593bafdb6d99ec3d332

See more details on using hashes here.

Provenance

The following attestation bundles were made for oxidize_pdf-0.14.0-cp310-abi3-manylinux_2_28_x86_64.whl:

Publisher: release.yml on bzsanti/oxidize-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oxidize_pdf-0.14.0-cp310-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for oxidize_pdf-0.14.0-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 00d79286fcdcebfb57e82b75e339dc70ae9634579d2a363bb59a02e18ec3a30c
MD5 76e70448dbe01e26b22adc9b851825cc
BLAKE2b-256 c9a3634b215638d6a4b202214810bbc77ffbb681ba25a2542c7a591af8acb0a3

See more details on using hashes here.

Provenance

The following attestation bundles were made for oxidize_pdf-0.14.0-cp310-abi3-manylinux_2_28_aarch64.whl:

Publisher: release.yml on bzsanti/oxidize-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oxidize_pdf-0.14.0-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for oxidize_pdf-0.14.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6edc44c029fca7ff999b7de9db49c0890b287c420fd966c62483505b3a420abc
MD5 0b7ef496906d64bf0ff19391fbabd7b6
BLAKE2b-256 c20a2b8bb8ab98d7ca85b022cce2e83b342487ae3e1cebbfc2ede2cd0ab2df60

See more details on using hashes here.

Provenance

The following attestation bundles were made for oxidize_pdf-0.14.0-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on bzsanti/oxidize-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oxidize_pdf-0.14.0-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for oxidize_pdf-0.14.0-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 79c65c5e6f3d93e3801b6cc0591ec137052da94f3e2be803442f238c9d377de0
MD5 1d91b8d72015f6d80f4a588c16afdd01
BLAKE2b-256 b0cffcdaa8633977f98f5893ad841ab58f8767e6afcad18b59c1b205c7057504

See more details on using hashes here.

Provenance

The following attestation bundles were made for oxidize_pdf-0.14.0-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on bzsanti/oxidize-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page