oxidize-pdf MCP Server

oxidize-pdf

Documentation · Context7 · Documentation publishing and indexing

Version 0.23.4 pins Rust core 5.5.6. See compatibility and validation.

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+

Version 0.23.4 pins Rust core 5.5.6, using the MIT-licensed oxidize-webpki RustCrypto provider for certificate verification. See the dependency policy for supported builds and limits. 0.23.4 release notes describe the signed-field permission fixes. New APIs include explicit text recovery, non-breaking-space normalization, build identification controls and incremental signature slots. See the API guide and validation.

The current develop branch contains post-release parity work. See the current capability inventory and Python/.NET comparison for the audited subset, missing bindings and inherited core limitations. Neither the core version nor the type stubs establish full functional parity; no global coverage percentage is claimed.

Why oxidize-pdf?

---

MCP Server

Expose the supported PDF tools to your AI agent:

oxidize-mcp

The built-in Model Context Protocol server exposes 12 tools, 5 static resources plus a session resource template, and 5 prompts over stdio. Install oxidize-pdf[mcp] to include its dependencies; the base library keeps MCP optional.

Version 0.20 uses FastMCP 4 and MCP Python SDK 2, with support for both modern and legacy stdio clients. See the migration guide for versions and installation routes.

If tools/list returns an empty array with an older installation (issue #198), upgrade to 0.20.0 or newer. These versions fix tool registration when starting server.py directly. On Windows, use the same Python environment for installation and startup:

python -m pip install --upgrade "oxidize-pdf[mcp]"

python -m oxidize_pdf.mcp.server

For a custom JSON-RPC client, send initialize, wait for its response, then send notifications/initialized before tools/list. Read newline-delimited JSON-RPC from stdout and keep stderr separate; the startup banner is written to stderr.

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. This package does not expose

a hosted HTTP endpoint. ChatGPT web needs a remote connection; developer-mode

testing can also use Secure MCP Tunnel

with a local stdio server. No ChatGPT plugin is published by this migration.

Available tools

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:

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)

Inspect tagged PDF structure

from pathlib import Path

from oxidize_pdf import TaggedPdfLimits, TaggedPdfValidationOptions, validate_tagged_pdf

report = validate_tagged_pdf( Path("input.pdf").read_bytes(), TaggedPdfValidationOptions(TaggedPdfLimits(max_depth=64)), ) for finding in report.findings: print(finding.severity, finding.code, finding.path, finding.message)

The report includes structure elements, artifacts, role/class maps, the parent number tree and content MCIDs. Original dictionary values remain typed PdfValue objects, including unknown attributes and reference generations. Results are immutable snapshots; returned lists and dictionaries are owned copies.

valid means the core validator found no error-level findings. It is not a PDF/UA certificate: an untagged PDF can have tagged=False, valid=True and a MissingStructureTree warning. Malformed input raises PdfParseError, locked input raises PdfEncryptionError, and exceeded validation budgets raise PdfError.

TaggedPdfLimits bounds visited objects, traversal depth, entries and decoded content bytes (defaults: 100,000; 256; 1,000,000; 256 MiB). These are core validator budgets, not a process memory or time limit: input copying and initial PDF parsing occur before traversal. No PDF bytes are modified.

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