Skip to main content
Glama
mcp-pdf-reader

mcp-pdf-reader

by pietermyb

PDF Reader MCP Server for VS Code

License: MIT Python Version

An MCP server that enables VS Code to view and analyze PDF documents using the Model Context Protocol (MCP).

This project was created using the Model Context Protocol Python SDK based on FastMCP.

Features

  • Open and read PDF documents

  • Extract text from PDFs (whole document or specific pages)

  • View PDF metadata

  • Generate summaries of PDF content

  • Extract text from specific pages or page ranges

  • Analyze PDF content and answer questions about it

Related MCP server: Re:portFlow

Installation

  1. Ensure you have Python 3.13+ installed

  2. Clone this repository

  3. Create a virtual environment:

uv venv .venv
source .venv/bin/activate
  1. Install dependencies:

uv pip install -e .

Docker

You can also run this MCP server using Docker:

Build the Docker Image

docker build -t pdf-reader-mcp .

Run the Container

docker run --name pdf-reader-mcp -it pdf-reader-mcp

Use with VS Code or Claude Desktop

When using Docker, update your MCP configuration to use the Docker container:

VS Code Configuration (Docker)

{
  "servers": {
    "pdf-reader": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm", 
        "-i",
        "pdf-reader-mcp"
      ]
    }
  }
}

Claude Desktop Configuration (Docker)

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm", 
        "-i",
        "pdf-reader-mcp"
      ]
    }
  }
}

Usage

This MCP server integrates with VS Code's MCP client to provide PDF reading capabilities. See the Tools and Prompts section below for details on available functionality.

Examples

MCP Tools in VS Code Copilot

This image shows the PDF Reader tools available in VS Code through the MCP protocol:

PDF Reader MCP Tools in VS Code Copilot

Example Usage

Here's an example of using the PDF Reader to analyze a document:

Example of PDF Reader usage

VS Code Configuration

The server is configured to run in VS Code through the .vscode/mcp.json file. VS Code must have the MCP extension installed to use this server.

To install the VS Code MCP extension:

  1. Open VS Code

  2. Go to Extensions (Ctrl+Shift+X or Cmd+Shift+X)

  3. Search for "Model Context Protocol"

  4. Install the extension from Microsoft

Once the extension is installed, VS Code will be able to communicate with this MCP server according to the configuration in your .vscode/mcp.json file. You can use the MCP server through VS Code's Copilot or any other MCP client built into VS Code.

Development

To make changes to this project:

  1. Modify the code in the src/pdf_reader_mcp directory

  2. Install in development mode: uv pip install -e .

  3. Test your changes in VS Code

Requirements

Tools and Prompts

Tools

The server implements the following tools:

  • open-pdf: Open a PDF file

    • Takes path as a required string argument

    • Returns a unique PDF ID for referencing in other operations

  • close-pdf: Close an open PDF file

    • Takes pdf_id as a required string argument

  • list-pdf-metadata: View metadata of an open PDF

    • Takes pdf_id as a required string argument

  • get-pdf-page-count: Get the total number of pages in a PDF

    • Takes pdf_id as a required string argument

  • get-pdf-page-text: Get the text content of a specific page in a PDF

    • Takes pdf_id as a required string argument

    • Takes page_number as a required integer argument (0-based index)

  • pdf-to-text: Extract all text from a PDF document

    • Takes pdf_id as a required string argument

    • Optional include_page_numbers as a boolean (default: true)

    • Optional start_page and end_page as integers to extract a specific range

Prompts

The server provides the following prompts:

  • summarize-pdf: Generate a summary of a PDF document

    • Required pdf_id argument that identifies the PDF

    • Optional style argument to control detail level (brief/detailed)

  • extract-text-from-pdf: Extract text from specific pages or page ranges

    • Required pdf_id argument

    • Optional page or page range arguments (page, start_page, end_page)

  • analyze-pdf: Analyze a PDF and answer questions about its content

    • Required pdf_id argument

    • Required question argument specifying what to analyze

    • Optional page_range argument to focus on specific pages

Quickstart

Install

VS Code

Configure VS Code to use the MCP server by editing .vscode/mcp.json in your project:

{
  "servers": {
    "pdf-reader": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "${workspaceFolder}",
        "run",
        "python",
        "-c",
        "from pdf_reader_mcp import main; main()"
      ]
    }
  }
}
{
  "servers": {
    "pdf-reader": {
      "type": "stdio",
      "command": "pdf-reader-mcp"
    }
  }
}

Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "${workspaceFolder}",
        "run",
        "pdf-reader-mcp"
      ]
    }
  }
}
{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "uvx",
      "args": [
        "pdf-reader-mcp"
      ]
    }
  }
}

Development

Building and Publishing

To prepare the package for distribution:

  1. Sync dependencies and update lockfile:

uv sync
  1. Build package distributions:

uv build

This will create source and wheel distributions in the dist/ directory.

  1. Publish to PyPI:

uv publish

Note: You'll need to set PyPI credentials via environment variables or command flags:

  • Token: --token or UV_PUBLISH_TOKEN

  • Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory "${workspaceFolder}" run pdf-reader-mcp

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

Contributing

  1. Fork the repo

  2. Create a new branch (feature-branch)

  3. Commit your changes

  4. Push to your branch and submit a PR!

License

This project is licensed under the MIT License.

Contact

For questions or support, reach out via GitHub Issues.

Available Tools

6 tools
close-pdfC

Close an open PDF file

Inputs: pdf_id (required).

get-pdf-page-countC

Get the page count of a PDF

Inputs: pdf_id (required).

get-pdf-page-textC

Get the text content of a specific page in a PDF

Inputs: pdf_id (required), page_number (required).

list-pdf-metadataC

List metadata of an open PDF

Inputs: pdf_id (required).

open-pdfC

Open a PDF file

Inputs: path (required).

pdf-to-textC

Extract all text from a PDF document

Inputs: pdf_id (required), include_page_numbers, start_page, end_page.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose targeting different PDF operations: opening/closing files, retrieving metadata, page-specific text, full text extraction, and page counting. There is no overlap in functionality that would cause agent confusion.

    Naming Consistency4/5

    The naming follows a consistent pattern with hyphen-separated descriptive names (e.g., open-pdf, get-pdf-page-text), but there is a minor deviation with 'pdf-to-text' which uses 'to' instead of a verb like 'extract'. Overall, the pattern is highly readable and predictable.

    Tool Count5/5

    With 6 tools, this server is well-scoped for PDF reading operations. Each tool serves a specific, essential function (open, close, metadata, page count, page text, full text), and there are no extraneous or missing tools for the domain.

    Completeness5/5

    The toolset provides complete coverage for PDF reading: open/close lifecycle, metadata access, page-level and full-text extraction, and page counting. There are no obvious gaps; agents can perform all core PDF reading tasks without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    Appeared in Searches