mcp-pdf-vision

An MCP (Model Context Protocol) server for PDF visual inspection and arXiv source download. It allows LLMs to "see" PDF pages as images and retrieve arXiv paper sources.

Features

• get_pdf_metadata — Get basic PDF information (page count, page size)
• inspect_pdf_visually — Render PDF pages as inline image items; payloads are base64-encoded JPEGs for visual inspection
• save_pdf_pages_locally — Render PDF pages into .mcp-pdf-vision/ inside the caller workspace and return the saved image paths
• download_arxiv_source — Download and extract arXiv paper TeX source by URL or ID

Prerequisites

• Python >= 3.10
• Poppler (required by pdf2image)

# macOS
brew install poppler

# Ubuntu / Debian
sudo apt-get install poppler-utils

# Windows (via conda)
conda install -c conda-forge poppler

Installation

# Using uv (recommended)
uv pip install mcp-pdf-vision

# Using pip
pip install mcp-pdf-vision

Release

Local publish

# Bump version in pyproject.toml first
rm -rf dist build *.egg-info
python -m pip install -U build twine
python -m build
twine check dist/*
twine upload dist/*

GitHub Actions publish

This repository includes .github/workflows/publish.yml for PyPI Trusted Publishing.

1. In PyPI, add this GitHub repository as a trusted publisher for mcp-pdf-vision.
2. Bump version in pyproject.toml.
3. Push a tag like v0.1.1.
4. GitHub Actions will build and publish the package automatically.

Usage

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "pdf-vision": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pdf-vision", "mcp-pdf-vision"]
    }
  }
}

MCP Inspector (for testing)

npx @modelcontextprotocol/inspector uv run mcp-pdf-vision

Direct execution

uv run mcp-pdf-vision

Note: The server uses stdio transport. Running it directly in a terminal will show a JSON parsing error — this is expected. Use an MCP client or the Inspector to interact with it.

Environment Variables

download_arxiv_source and debug image export now prefer the client-provided MCP roots (roots/list), so files are written into the caller workspace instead of the server process directory. If the client does not expose roots, the server falls back to MCP_OUTPUT_DIR / MCP_DEBUG_IMAGE_DIR, then PWD / process cwd (useful for stdio clients that launch the server in the active workspace).

Visual Inspection Modes

• inspect_pdf_visually returns inline MCP image content items. Each item contains a base64-encoded JPEG payload, so the client can inspect the page without creating files.
• save_pdf_pages_locally writes PNG files directly into <workspace>/.mcp-pdf-vision/ with names like page-1-20260318T123456789012Z.png, then returns the absolute paths for downstream tools or local image viewing.

License

MIT