PDF Processor Server

FastMCP PDF Processing Server

An MCP server built with FastMCP (STDIO transport) offering PDF utilities: text extraction, metadata, merge/split/rotate, and PDF↔image conversion.

SPANISH VERSION [README.es.md]

Quick Start (Windows PowerShell)

python -m venv .venv
\.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
python -m fastmcp_pdf_server

If installed as a package, you may also run: `` fastmcp-pdf-server ``

Quick Start (Linux/macOS)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python -m fastmcp_pdf_server

MCP Integration

• Transport: STDIO. Do not print to stdout/stderr; logs go to file.
• Server name/version: from config (server_name, server_version).
• Tools are registered using @app.tool() and return structured outputs with a meta block containing operation_id and execution_ms.

Claude Desktop config example

Add to claude_desktop_config.json (Update with your own File System Path): ``json { "mcpServers": { "pdf-processor-server": { "command": "D:\\Github Projects\\mcp_pdf_server\\.venv\\Scripts\\python.exe", "args": [ "-m", "fastmcp_pdf_server" ], "env": { "MAX_FILE_SIZE_MB": "50", "TEMP_DIR": "D:\\Github Projects\\mcp_pdf_server\\temp_files", "LOG_LEVEL": "DEBUG", "LOG_FILE_PATH": "D:\\Github Projects\\mcp_pdf_server\\logs\\fastmcp_pdf_server.log", "SERVER_NAME": "pdf-processor-server", "SERVER_VERSION": "1.0.0", "PATH": "%PATH%;C:\\poppler-25.07.0\\Library\\bin" } } } ``

Note: If you update dependencies (e.g., we added requests for URL uploads), reinstall with: `` pip install -r requirements.txt ``

Claude Desktop config example (Linux)

Add to claude_desktop_config.json: ``json { "mcpServers": { "pdf-processor-server": { "command": "python3", "args": [ "-m", "fastmcp_pdf_server" ], "env": { "MAX_FILE_SIZE_MB": "50", "TEMP_DIR": "/home/you/dev/mcp_pdf_server/temp_files", "LOG_LEVEL": "DEBUG" } } } } ``

Claude Desktop config example (macOS)

Add to claude_desktop_config.json: ``json { "mcpServers": { "pdf-processor-server": { "command": "python3", "args": [ "-m", "fastmcp_pdf_server" ], "env": { "MAX_FILE_SIZE_MB": "50", "TEMP_DIR": "/Users/you/dev/mcp_pdf_server/temp_files", "LOG_LEVEL": "DEBUG" } } } } ``

Programmatic usage (Python)

import asyncio
from fastmcp import Client

async def main():
    client = Client(command="python", args=["-m", "fastmcp_pdf_server"])
    await client.start()
    try:
        info = await client.call_tool("server_info")
        print(info)
    finally:
        await client.close()

asyncio.run(main())

Exposed Tools (API)

All tools return structured data; many responses include meta.operation_id and meta.execution_ms. Some tools return lists (arrays). These are marked with FastMCP's x-fastmcp-wrap-result, so clients receive { "result": [...] } at the RPC layer.

MCP Tools Reference

Each tool lists: purpose, inputs, outputs, behavior, examples, and notes about errors and usage.

---

Utilities / Server

• server_info()
• Purpose: Return basic server info and configuration snapshot (non-secret).
• Inputs: None
• Returns: dict with keys:
• name (str): server name from settings
• version (str): server version from settings
• max_file_size_mb (int): maximum configured file size in megabytes
• temp_dir (str): absolute path to temporary files directory
• log_file (str): absolute path to the log file
• meta (dict): operation metadata: operation_id (hex), execution_ms (int)
• Errors: none expected; if configuration missing, underlying access may raise exceptions.
• Example:
• Call: { "name": "server_info" }
• Response: { "name": "mcp-pdf", "version": "1.0.0", "meta": { ... } }

• list_temp_resources(content_type: Optional[str] = None, max_items: Optional[int] = 100) -> list[dict]
• Purpose: List files currently in the server temp directory with optional filtering by content type.
• Inputs:
• content_type (optional str): MIME filter; supported examples: application/pdf, image/png, image/jpeg.
• max_items (optional int): maximum number of entries to return (default 100). If set to null or 0, defaults to 100.
• Returns: list of resource dicts (each):
• path (str): absolute path to the temp file
• size (int): size in bytes
• created (str): creation timestamp (ISO or file-manager-specific format)
• content_type (str): MIME type of resource
• filename (str): filename only
• extension (str): lowercased file extension (e.g. .pdf)
• directory (str): parent directory of the file
• Behavior: Cleans up expired temp files before listing. Result list is sliced to max_items.
• Errors: Raises ValueError if internal listing fails.
• Example call:
• { "name": "list_temp_resources", "arguments": { "content_type": "application/pdf" } }

• get_pdf_info(file_path: str) -> dict
• Purpose: Read a PDF headers and basic info without extracting pages/text.
• Inputs:
• file_path (str): path to an existing file on disk (absolute or relative). Must be accessible to the server.
• Returns: dict:
• pages (int): number of pages
• size (int): file size in bytes
• version (str|None): PDF header/version info (if available)
• encrypted (bool): whether the PDF is encrypted
• meta (dict): operation_id, execution_ms
• Errors:
• Raises ValueError if file not found.
• May raise other errors if the file is not a PDF or is corrupted.

• get_resource_base64(file_path: str) -> dict
• Purpose: Return base64-encoded contents of a file inside the server temp directory.
• Inputs:
• file_path (str): path; must be inside the configured temp directory. The function enforces this.
• Returns: dict:
• path (str): resolved path inside temp
• base64 (str): Base64-encoded content of the file
• meta (dict): operation metadata
• Errors:
• Raises ValueError if the path is outside temp or file missing.
• Notes: Use this to fetch content for download via MCP where direct file transfers aren't available.

---

Uploads

• upload_file(file: Any, filename: Optional[str] = None) -> dict
• Purpose: Persist an uploaded file into the server temp directory.
• Inputs:
• file (Any): Accepts:
• a full path string to a local file
• a short filename that refers to a file already stored in temp
• bytes or file-like object
• dicts containing base64 and filename (will be saved to temp)
• filename (Optional[str]): optional filename hint used when saving raw bytes.
• Returns: dict:
• path (str): absolute path to the saved file
• filename (str): saved filename
• directory (str): directory containing the file
• meta (dict): operation metadata
• Errors:
• Raises ValueError with a descriptive message on failure (network, decoding, IO).
• Example:
• To upload base64: call upload_file with file = { "base64": "<...>", "filename": "my.pdf" }.

• upload_file_base64(base64: str, filename: str) -> dict
• Purpose: Upload raw Base64 content and persist to temp storage.
• Inputs:
• base64 (str): Base64 string
• filename (str): filename to use when saving
• Returns: dict:
• path, filename, directory, size (int), meta
• Errors: Raises ValueError on decoding or write errors.

• upload_file_url(url: str, filename: Optional[str] = None) -> dict
• Purpose: Download a remote file (HTTP/HTTPS) and save to temp storage.
• Inputs:
• url (str): direct URL to file
• filename (Optional[str]): optional override filename
• Returns: dict with path, filename, directory, meta.
• Notes: Requires requests package to be available in the environment.

---

Text Extraction

• extract_text(file: Any, encoding: Optional[str] = "utf-8") -> dict
• Purpose: Extract all text from a PDF and return summary metrics.
• Inputs:
• file (Any): same resolver rules as upload_file (path, temp filename, bytes, base64 dict).
• encoding (str|None): encoding used when returning text (default utf-8).
• Returns: dict:
• text (str): full extracted text
• page_count (int): number of pages processed
• char_count (int): number of characters in text
• meta (dict): includes resolved_path pointing to saved temp file
• Errors:
• Raises ValueError with helpful hint explaining how to provide the file if extraction fails.
• Example usage:
• Upload a file with upload_file, then call extract_text with the returned path.

• extract_text_by_page(file: Any, pages: Optional[List[int]] = None, page_range: Optional[str] = None, encoding: Optional[str] = "utf-8") -> list[dict]
• Purpose: Extract text from specific pages or a page range.
• Inputs:
• file (Any): resolver rules as above
• pages (Optional[List[int]]): list of 1-based page indices to extract (e.g., [1,3,5]).
• page_range (Optional[str]): range expression like "1-3,5" (parser in utils.parsers will be used).
• encoding (Optional[str]): text encoding
• Returns: list of page result dicts; each dict typically contains:
• page_number (int)
• text (str)
• char_count (int)
• Behavior: If both pages and page_range are provided, pages takes precedence. The tool returns a list directly (framework wraps list results).
• Errors: Raises ValueError on invalid pages or extraction failures.

• extract_metadata(file: Any) -> dict
• Purpose: Extract detailed PDF metadata (author, title, producer, creation/mod dates, custom metadata, etc.).
• Inputs: file same as above.
• Returns: dict containing metadata keys found in the PDF plus meta operation info.

---

Conversion

• pdf_to_images(file_path: str, output_dir: str, format: str = "png", dpi: int = 150, pages: Optional[List[int]] = None) -> list[dict]
• Purpose: Convert one or more PDF pages to image files.
• Inputs:
• file_path (str): path to the PDF on disk (absolute or temp path).
• output_dir (str): directory where generated images will be written.
• format (str): image format, e.g., png, jpeg.
• dpi (int): resolution for conversion (default 150).
• pages (Optional[List[int]]): list of 1-based pages to render; None for all pages.
• Returns: list of dicts for each generated image:
• path (str), page_number (int), size (int), format (str)
• Notes: Implementation uses pdf2image and PIL; ensure dependencies and poppler are installed on the host.

• images_to_pdf(image_paths: List[str], output_path: str, page_size: str = "A4", orientation: str = "portrait") -> dict
• Purpose: Create a PDF document from multiple images.
• Inputs:
• image_paths (List[str]): list of image file paths in order
• output_path (str): path for the generated PDF
• page_size (str): e.g., A4, Letter (processor maps to physical sizes)
• orientation (str): portrait or landscape
• Returns: dict with success info and meta including operation timing.

---

PDF Manipulation

• merge_pdfs(input_files: List[str], output_path: str) -> dict
• Purpose: Merge multiple PDF files into a single PDF.
• Inputs:
• input_files (List[str]): file paths
• output_path (str): destination path
• Returns: dict with details (e.g., path) and meta.

• split_pdf(file_path: str, split_ranges: List[Dict[str, Any]]) -> list[dict]
• Purpose: Split a PDF into multiple files by page ranges.
• Inputs:
• file_path (str): source PDF
• split_ranges (List[Dict]): each dict should describe start and end pages and optional filename.
• Returns: list of generated files info dicts.

• rotate_pages(file_path: str, rotations: List[Dict[str, int]], output_path: str) -> dict
• Purpose: Rotate specific pages in a PDF and write to output_path.
• Inputs:
• file_path (str): source PDF
• rotations (List[Dict]): each dict should include page (1-based) and degrees (e.g., 90, 180, 270).
• output_path (str): target PDF path
• Returns: dict with path and meta.

---

Notes:

• All tools log an operation_id and execution time in ms in the returned meta object.
• Tools that return lists set x-fastmcp-wrap-result=true for the framework so they are returned as bare lists.
• Tools will raise ValueError for user-facing errors; internal exceptions are logged.
• For file inputs, prefer uploading first via upload_file to ensure files are in the server temp directory.
• page_range syntax uses utils.parsers.parse_page_range: e.g., "1-3,5,7-9".
• If both pages and page_range are passed, pages takes precedence.
• Image conversion requires Poppler (see below).

Example JSON: extract_text (simple)

• Request arguments:

{
  "file": "C:/path/to/input.pdf",
  "encoding": "utf-8"
}

• Response shape:

{
  "text": "... full extracted text ...",
  "page_count": 3,
  "char_count": 1234,
  "meta": { "operation_id": "<hex>", "execution_ms": 42 }
}

Uploading files (Claude Desktop and clients)

Claude may not automatically send binary file contents. Use one of these upload tools to persist a file to the server temp directory, then reference it by short filename in subsequent calls.

1) Upload a file (generic)

• Tool: upload_file
• Request:

{
  "name": "upload_file",
  "arguments": {
    "file": { "base64": "<BASE64_DATA>", "filename": "document.pdf" }
  }
}

• Response contains filename and absolute path under the server temp_dir.

2) Upload a file as base64 (explicit schema)

• Tool: upload_file_base64
• Request:

{
  "name": "upload_file_base64",
  "arguments": { "base64": "<BASE64_DATA>", "filename": "document.pdf" }
}

3) Upload a file from URL (explicit schema)

• Tool: upload_file_url
• Request:

{
  "name": "upload_file_url",
  "arguments": { "url": "https://example.com/document.pdf", "filename": "document.pdf" }
}

4) Extract text using the saved short filename

• Request:

{
  "name": "extract_text",
  "arguments": { "file": "document.pdf" }
}

Alternative: provide a URL to upload_file (requires requests installed): ``json { "name": "upload_file", "arguments": { "file": { "url": "https://example.com/document.pdf", "filename": "document.pdf" } } } ``

Manual option: run server_info to get temp_dir, copy your file into that directory, then call tools with the short filename.

Example JSON: merge_pdfs

• Request arguments:

{
  "input_files": [
    "C:/path/a.pdf",
    "C:/path/b.pdf"
  ],
  "output_path": "C:/path/merged.pdf"
}

• Response shape:

{
  "output_path": "C:/path/merged.pdf",
  "page_count": 10,
  "size": 456789,
  "meta": { "operation_id": "<hex>", "execution_ms": 87 }
}

Configuration

Configuration is loaded via pydantic-settings from .env and environment variables.

Env vars (case-insensitive):

• MAX_FILE_SIZE_MB (int, default 50): Max file size for inputs.
• LOG_LEVEL (str, default INFO): Logging level.
• LOG_FILE_PATH (str, default logs/pdf-processor-server.log): Log file path.
• TEMP_DIR (str, default temp_files): Working temp storage directory.
• SERVER_NAME (str, default pdf-processor-server): Server name.
• SERVER_VERSION (str, default 1.0.0): Server version.

Path helpers:

• TEMP_DIR resolves to absolute settings.temp_path.
• LOG_FILE_PATH resolves to absolute settings.log_path.

Storage & Security

• Temp files are stored under TEMP_DIR and cleaned up automatically after 24h of inactivity.
• ensure_within_temp(path) prevents reading files outside TEMP_DIR for base64 retrieval.
• Validators enforce allowed extensions and size limits for PDFs and images.

Logging & Telemetry

• Rotating logs at LOG_FILE_PATH (10MB x 5). No stdout/stderr prints.
• Each tool returns meta.operation_id and meta.execution_ms for traceability.
• Server banner and lifecycle logs are emitted by FastMCP at startup/shutdown.

Windows: Poppler for pdf2image

pdf2image requires Poppler binaries.

• Download: https://github.com/oschwartz10612/poppler-windows/releases/
• Extract, add poppler-*/Library/bin to your PATH.
• Verify: pdftoppm -v prints a version. If not available, pdf_to_images tools will raise helpful errors.

Linux: Poppler for pdf2image

pdf2image requires Poppler binaries. Install via your package manager:

• Debian/Ubuntu: sudo apt update && sudo apt install -y poppler-utils
• Fedora: sudo dnf install -y poppler-utils
• Arch: sudo pacman -S --noconfirm poppler
• Verify: pdftoppm -v prints a version.

macOS: Poppler for pdf2image

Install Poppler with Homebrew: `` brew install poppler ` If Homebrew is in /opt/homebrew/bin (Apple Silicon), ensure your shell PATH includes it. Verify: pdftoppm -v`.

Developer Guide

Project layout

• src/fastmcp_pdf_server/
• main.py: Builds FastMCP app, registers tools, runs via STDIO.
• config.py: Pydantic settings for env and paths.
• utils/: Logger, validators, parsers.
• services/: PDF and image operations, file manager.
• tools/: Thin async wrappers exposing services as MCP tools.

Install & Run

python -m venv .venv
\.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
python -m fastmcp_pdf_server

Linux/macOS: `` python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt cp .env.example .env python -m fastmcp_pdf_server ``

Tests

pytest -q

Conversion tests are skipped if Poppler (pdftoppm) is not found.

Troubleshooting

• Startup hangs after banner: normal for STDIO mode (waiting for an MCP client).
• pdf2image errors: ensure Poppler on PATH; retry shell after updating PATH.
• ValueError: File not found or Invalid file extension: check inputs and validators.
• Large files slow/timeout: reduce dpi, use page-range, or increase resources.

Performance Notes

• Max file size is enforced; adjust MAX_FILE_SIZE_MB if needed.
• Prefer page-scoped ops for large PDFs.
• Lower dpi for faster PDF→image conversions.

Optional HTTP Mode (advanced)

FastMCP supports a streamable HTTP transport. This server defaults to STDIO. For experimentation, you can run an HTTP endpoint:

# run_http.py
import asyncio
from fastmcp_pdf_server.main import build_app

async def main():
  app = build_app()
  await app.run_http_async(host="127.0.0.1", port=8000, path="mcp")

asyncio.run(main())

Happy Coding!