Registry / web-framework / pdf-tools-mcp

pdf-tools-mcp

library0.1.4pypypi✓ verified 21d ago

pdf-tools-mcp is a FastAPI-based server for reading and manipulating PDF documents. It provides a RESTful API for common PDF operations like splitting, merging, extracting pages, adding content, watermarking, converting, compression, and OCR. The current version is 0.1.4, and its release cadence is irregular, driven by feature additions and maintenance.

web-framework data

pip install pdf-tools-mcp

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · PDF-TOOLS-MCP

pdf-tools-mcp

web-frameworkpythonv0.1.4

Install

11.4s avg

Import

2940ms

Disk

118MB

Pass rate

4/ 10

Env Coverage4 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.1.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

py 3.11

✕ build_error

py 3.12

✓ —

✓ 11.4s

py 3.13

✓ —

✓ 11.4s

py 3.9

✕ build_error

118MB installed

● package 118MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

server

✓ from pdf_tools_mcp import server

✗ from pdf_tools_mcp.main import app

This quickstart demonstrates how to install and run the `pdf-tools-mcp` server, and how to perform a basic health check using `curl` or a Python `requests` client. Remember to run the `python -m pdf_tools_mcp.main` command in a separate terminal to start the server before making API requests. The server typically runs on `http://127.0.0.1:8000` by default.

# 1. Install the library pip install pdf-tools-mcp # 2. Run the PDF tools server # In your terminal, run: # python -m pdf_tools_mcp.main # 3. Access the API (e.g., using curl in another terminal) # curl http://127.0.0.1:8000/api/v1/health # Expected output for health check (after server starts): # {"status":"ok"} # Example Python client interaction (requires 'requests') import requests BASE_URL = "http://127.0.0.1:8000/api/v1" try: response = requests.get(f"{BASE_URL}/health") response.raise_for_status() # Raise an exception for HTTP errors print(f"Health check: {response.json()}") # Example: Upload a PDF (assuming you have 'example.pdf' locally) # with open('example.pdf', 'rb') as f: # files = {'file': ('example.pdf', f, 'application/pdf')} # upload_response = requests.post(f"{BASE_URL}/pdf/split", files=files, # params={'pages': '1'}) # upload_response.raise_for_status() # print(f"Upload/Split response: {upload_response.json()}") except requests.exceptions.ConnectionError: print("Error: Could not connect to the pdf-tools-mcp server. Is it running?") except requests.exceptions.RequestException as e: print(f"An error occurred: {e}")

pdf-tools-mcp --version

Debug

Known issues

gotchapdf-tools-mcp is primarily designed as a standalone FastAPI server, not a Python library for direct function calls. Its core functionality is exposed via HTTP endpoints. Attempting to import and use internal modules directly without running the server might lead to unexpected behavior or incomplete functionality.

fix

Run the server using `python -m pdf_tools_mcp.main` and interact with it via HTTP requests (e.g., using `requests` in Python or `curl`).

affects: 0.1.0+

gotchaSeveral advanced features like OCR, HTML to PDF conversion, and advanced PDF generation depend on optional 'extras' dependencies. If you don't install these, the corresponding API endpoints or features will not work and might return HTTP 500 errors or validation failures.

fix

Install the package with the required extras: `pip install pdf-tools-mcp[ocr,weasyprint,reportlab]` for full functionality. Check the `pyproject.toml` or `README` for specific feature-to-extra mappings.

affects: 0.1.0+

breakingThe library explicitly requires Python 3.12 or newer. Running it with older Python versions (e.g., 3.11 or 3.10) will result in installation failures or runtime errors due to syntax or dependency incompatibilities.

fix

Ensure your Python environment is version 3.12 or higher. Consider using `pyenv` or `conda` to manage multiple Python versions if needed.

affects: 0.1.0+

gotchaWhen interacting with file upload endpoints (e.g., for splitting or merging PDFs), ensure you correctly format your `multipart/form-data` request. For Python's `requests` library, use the `files` parameter with a tuple `('filename', file_object, 'content_type')`.

fix

Refer to FastAPI's documentation on `UploadFile` and `requests` library documentation on file uploads for correct client-side implementation. Example: `files = {'file': ('my_document.pdf', open('my_document.pdf', 'rb'), 'application/pdf')}`.

affects: 0.1.0+

Upgrade

Version history

0.1.4latest on PyPI · released Aug 10, 2025

Audit

Dependencies

fastapirequiredCore web framework for the server.

uvicornrequiredASGI server for running the FastAPI application.

pypdfrequiredPrimary library for PDF manipulation.

PillowrequiredImage processing for adding content or converting.

opencv-python-headlessoptionalRequired for OCR functionality.

pytesseractoptionalRequired for OCR functionality.

weasyprintoptionalRequired for HTML to PDF conversion.

reportlaboptionalRequired for PDF generation features.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/lockon-n/pdf-tools-mcp#readme ↗

packagehttps://pypi.org/project/pdf-tools-mcp/ ↗

docshttps://github.com/lockon-n/pdf-tools-mcp#readme ↗