PDF LocalVision MCP

An MCP server that performs native multimodal Visual Readings of PDF documents using local vision-language models (via oMLX on Apple Silicon or any OpenAI-compatible vision endpoint such as Ollama, vLLM, or LM Studio).

Instead of extracting embedded PDF text layers or running separate OCR pre-parsers, pdf-localvision-mcp rasterizes PDF pages in-memory to PNG (pymupdf) with dimensions snapped to multiples of 28 (<= 1792px by default) and processes them through a two-tier grounded reading pipeline:

1. Grounded Page Breakdown (## [Page N]): Reading-order Markdown prose, HTML <table> tags (preserving rowspan/colspan), LaTeX equations (\(...\) / \[...\]), linearized chart data tables & diagrams, and verbatim anchor quotes (> "..." [Page N]).

2. Executive Synthesis: A source-grounded document synthesis where every claim carries an inline [Page N] citation.

Prerequisites: Vision Model Backend

Option A: Local oMLX (Recommended for Apple Silicon)

1. Install oMLX:

brew tap jundot/omlx && brew install omlx
# or via pip / uv:
uv tool install omlx

2. Configure the Q-Vision alias in ~/.omlx/model_settings.json mapped to Qwen2.5-VL-7B-Instruct-8bit:

{
  "version": 1,
  "models": {
    "Qwen2.5-VL-7B-Instruct-8bit": {
      "model_alias": "Q-Vision"
    }
  }
}

3. Start the oMLX server on http://localhost:8000/v1:

# Option 1: Start the managed background daemon
omlx start

# Option 2: Serve directly
omlx serve mlx-community/Qwen2.5-VL-7B-Instruct-8bit --port 8000

Option B: Ollama, vLLM, or any OpenAI-Compatible Vision Server

Run any vision model supporting image inputs (e.g., llama3.2-vision, qwen2.5-vl, etc.):

ollama run llama3.2-vision

Then point pdf-localvision-mcp to it via VISION_BASE_URL (or OPENAI_BASE_URL) and VISION_MODEL (or OPENAI_MODEL).

Related MCP server: PDF MCP Flow

Running & Registering the MCP Server

Quick Start with uvx (No clone needed)

# Run directly from GitHub
uvx --from git+https://github.com/majdaleryani/pdf-localvision-mcp pdf-localvision-mcp

From Local Clone

git clone https://github.com/majdaleryani/pdf-localvision-mcp.git
cd pdf-localvision-mcp

# Run via uv
uv run pdf-localvision-mcp

Client Configuration Examples

1. Antigravity (~/.gemini/config/mcp_config.json)

{
  "mcpServers": {
    "pdf-localvision": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/majdaleryani/pdf-localvision-mcp",
        "pdf-localvision-mcp"
      ],
      "env": {
        "VISION_BASE_URL": "http://localhost:8000/v1",
        "VISION_MODEL": "Q-Vision"
      },
      "timeout": 300000
    }
  }
}

2. Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "pdf-localvision": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/majdaleryani/pdf-localvision-mcp",
        "pdf-localvision-mcp"
      ],
      "env": {
        "VISION_BASE_URL": "http://localhost:8000/v1",
        "VISION_MODEL": "Q-Vision"
      }
    }
  }
}

Or via Claude Code CLI:

claude mcp add pdf-localvision -- uvx --from git+https://github.com/majdaleryani/pdf-localvision-mcp pdf-localvision-mcp

3. Cursor (~/.cursor/mcp.json or .cursor/mcp.json)

{
  "mcpServers": {
    "pdf-localvision": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/majdaleryani/pdf-localvision-mcp",
        "pdf-localvision-mcp"
      ],
      "env": {
        "VISION_BASE_URL": "http://localhost:8000/v1",
        "VISION_MODEL": "Q-Vision"
      }
    }
  }
}

MCP Tool Reference: read_pdf_vision

Environment Variables

Running Tests

uv run pytest
uv run pyright

License

MIT License. See LICENSE for details.