PDF Tools MCP Server

Warnings

• gotcha pdf-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`).
• gotcha Several 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.
• breaking The 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.
• gotcha When 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')}`.

Install

• pip install pdf-tools-mcp Install core package
• pip install pdf-tools-mcp[ocr,weasyprint,reportlab] Install with optional dependencies

Imports

• app

  from pdf_tools_mcp.main import app

  While this imports the FastAPI app instance, the primary way to use pdf-tools-mcp is by running it as a server via `python -m pdf_tools_mcp.main`, not by importing its components for direct library use. This import is mainly for programmatic setup or testing.

Quickstart

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}")