bzsanti/oxidize-python

> Rust core pinned to **5.4.2**. 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
**Platforms:** Linux (x86_64, aarch64) | macOS (x86_64, Apple Silicon) | Windows (x86_64)
**Requires:** Python 3.10+
Version 0.22.0 pins Rust core **5.4.2**, using the MIT-licensed oxidize-webpki
RustCrypto provider for certificate verification. See the
dependency policy for supported builds and limits.
New APIs include explicit text recovery, non-breaking-space normalization,
build identification controls and incremental signature slots. See the
API guide and validation.
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:
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:
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:
GitHub Copilot (VS Code) integration
Copilot's agent mode speaks MCP. Add .vscode/mcp.json to your workspace:
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:
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
| 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 |