# MCP PDF Reader
**Available Languages:** [🇬🇧 English](README.md) | [🇪🇸 Español](README.es.md)
A powerful **Model Context Protocol (MCP)** server that empowers AI assistants like Claude and GitHub Copilot to intelligently interact with PDF documents. Extract text, metadata, search content, and retrieve embedded images—all through a standardized, LLM-friendly interface.
Not OCR-based.
**Current Version:** 1.0.0
**Package:** `@rturv/mcp-pdf-reader`
**License:** MIT
## Quick Start
### Installation
```bash
npm install -g @rturv/mcp-pdf-reader
```
### Run the Server
```bash
mcp-pdf-reader
```
## Configuration
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"pdf-reader": {
"command": "mcp-pdf-reader"
}
}
}
```
**Location:**
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/claude/claude_desktop_config.json`
### GitHub Copilot (VS Code)
Add to `mcpServers.json`:
```json
{
"mcpServers": {
"pdf-reader": {
"command": "mcp-pdf-reader",
"args": [],
"disabled": false
}
}
}
```
**Location:** `%APPDATA%\Code\User\globalStorage\github.copilot-chat\mcpServers.json`
See [COPILOT_CONFIG.md](COPILOT_CONFIG.md) for additional installation methods.
## Features
- ✅ **Full Text Extraction** - Extract complete text from PDF files
- ✅ **Metadata Extraction** - Retrieve title, author, creation date, and more
- ✅ **Page Range Reading** - Extract text from specific pages
- ✅ **Text Search** - Find text with surrounding context
- ✅ **Page Count** - Get total page count
- ✅ **Image Extraction** - List and extract embedded images in Base64
- ✅ **Standards Compliant** - Follows MCP specification for seamless LLM integration
## Tools Reference
This MCP server exposes 7 tools for comprehensive PDF manipulation. All tools are accessible through Claude Desktop, GitHub Copilot, and other MCP-compatible clients.
### 1. `read_pdf`
**Purpose:** Extract all text content from a PDF file. Use this as your primary method for understanding PDF document content.
**When to use:**
- Reading entire document content
- Getting full document text for summarization or analysis
- Extracting content when combined with metadata
**Input Parameters:**
```json
{
"filePath": "string (required) - Absolute path to the PDF file",
"includeMetadata": "boolean (optional, default: false) - Include PDF metadata in response"
}
```
**Example Request:**
```json
{
"filePath": "C:/Documents/report.pdf",
"includeMetadata": true
}
```
**Example Response:**
```json
{
"text": "Executive Summary\n\nThis report details Q4 2025 performance...",
"metadata": {
"title": "Q4 2025 Performance Report",
"author": "Analytics Team",
"subject": "Quarterly Report",
"creator": "Microsoft Word",
"producer": "iLovePDF",
"creationDate": "D:20250115120000Z",
"modificationDate": "D:20250115150000Z",
"keywords": "Q4, report, performance",
"totalPages": 12
},
"pageCount": 12
}
```
---
### 2. `get_pdf_metadata`
**Purpose:** Extract document metadata without reading the full text. Ideal for quick document inspection.
**When to use:**
- Identifying document properties (author, title, dates)
- Quick document validation
- Building document catalogs
- Checking modification dates
**Input Parameters:**
```json
{
"filePath": "string (required) - Absolute path to the PDF file"
}
```
**Example Request:**
```json
{
"filePath": "C:/Documents/contract.pdf"
}
```
**Example Response:**
```json
{
"title": "Service Agreement 2025",
"author": "Legal Department",
"subject": "Service Terms & Conditions",
"creator": "Adobe InDesign",
"producer": "Adobe PDF Library",
"creationDate": "D:20250101090000Z",
"modificationDate": "D:20250110140000Z",
"keywords": "service, agreement, contract",
"totalPages": 8
}
```
---
### 3. `read_pdf_pages`
**Purpose:** Extract text from a specific page or range of pages. Use this for targeted content extraction.
**When to use:**
- Reading specific sections of a document
- Analyzing particular chapters or pages
- Extracting cover pages or specific reports within a multi-part document
- Handling large PDFs by reading sections
**Input Parameters:**
```json
{
"filePath": "string (required) - Absolute path to the PDF file",
"startPage": "number (required) - Starting page number (1-indexed)",
"endPage": "number (optional) - Ending page number. If omitted, defaults to startPage"
}
```
**Example Request (single page):**
```json
{
"filePath": "C:/Documents/thesis.pdf",
"startPage": 1
}
```
**Example Request (page range):**
```json
{
"filePath": "C:/Documents/thesis.pdf",
"startPage": 5,
"endPage": 12
}
```
**Example Response:**
```json
{
"text": "Chapter 2: Literature Review\n\nThis chapter examines existing research...",
"startPage": 5,
"endPage": 12,
"totalPages": 45
}
```
---
### 4. `search_pdf`
**Purpose:** Search for text within a PDF and retrieve all matches with surrounding context.
**When to use:**
- Finding specific terms or phrases
- Locating sections by keyword
- Validating content presence
- Building keyword-based summaries
- Compliance checking (finding specific clauses)
**Input Parameters:**
```json
{
"filePath": "string (required) - Absolute path to the PDF file",
"searchTerm": "string (required) - Text to search for",
"caseSensitive": "boolean (optional, default: false) - Case-sensitive search"
}
```
**Example Request:**
```json
{
"filePath": "C:/Documents/policy.pdf",
"searchTerm": "termination clause",
"caseSensitive": false
}
```
**Example Response:**
```json
[
{
"page": 3,
"text": "termination clause",
"context": "...either party may invoke the termination clause without prior written notice...",
"position": 456
},
{
"page": 7,
"text": "termination clause",
"context": "...In accordance with Section 4.2, the termination clause becomes effective...",
"position": 1230
}
]
```
---
### 5. `get_pdf_page_count`
**Purpose:** Get the total number of pages in a PDF without reading content.
**When to use:**
- Validating PDF integrity
- Determining if a PDF is empty
- Planning page range extractions
- Batch processing logic based on document size
**Input Parameters:**
```json
{
"filePath": "string (required) - Absolute path to the PDF file"
}
```
**Example Request:**
```json
{
"filePath": "C:/Documents/manual.pdf"
}
```
**Example Response:**
```json
{
"pageCount": 247
}
```
---
### 6. `list_pdf_images`
**Purpose:** List all images embedded in a PDF with their metadata and locations.
**When to use:**
- Discovering embedded images before extraction
- Getting image dimensions and types
- Planning image extraction operations
- Validating image content presence
**Input Parameters:**
```json
{
"filePath": "string (required) - Absolute path to the PDF file"
}
```
**Example Request:**
```json
{
"filePath": "C:/Documents/presentation.pdf"
}
```
**Example Response:**
```json
{
"images": [
{
"index": 0,
"page": 2,
"name": "Image42",
"width": 800,
"height": 600,
"type": "JPEG"
},
{
"index": 1,
"page": 5,
"name": "Image43",
"width": 1024,
"height": 768,
"type": "PNG"
},
{
"index": 2,
"page": 8,
"name": "Image44",
"width": 640,
"height": 480,
"type": "TIFF"
}
]
}
```
---
### 7. `extract_pdf_image`
**Purpose:** Extract a specific image from a PDF and return it as Base64-encoded data.
**When to use:**
- Recovering images from PDFs
- Converting PDF images to standard formats
- Processing visual content for analysis
- Archiving embedded images
**Before using:** Call `list_pdf_images` first to discover available images and their indices.
**Input Parameters:**
```json
{
"filePath": "string (required) - Absolute path to the PDF file",
"imageIndex": "number (required) - Image index from list_pdf_images (0-indexed)"
}
```
**Example Request:**
```json
{
"filePath": "C:/Documents/presentation.pdf",
"imageIndex": 0
}
```
**Example Response:**
```json
{
"index": 0,
"page": 2,
"name": "Image42",
"width": 800,
"height": 600,
"type": "JPEG",
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}
```
**Note:** Image data is Base64 encoded. Decode it to save as a file (e.g., using `atob()` in JavaScript or `base64 -d` in bash).
## Testing with MCP Inspector
The MCP Inspector is an interactive tool for testing and debugging MCP servers. It provides a web-based UI to invoke tools and inspect responses in real-time.
### Installation
```bash
npm install -g @modelcontextprotocol/inspector
```
### Running the Server with Inspector
1. **Start the MCP server in debug mode:**
```bash
mcp-pdf-reader
```
2. **In a separate terminal, launch the Inspector:**
```bash
mcp-inspector node dist/index.js
```
Or if using the global npm package:
```bash
mcp-inspector npx @rturv/mcp-pdf-reader
```
3. **Open the web UI:** The Inspector will provide a URL (typically `http://localhost:5173`). Open it in your browser.
### Using the Inspector
#### Example: Extract text from a PDF
1. In the Inspector UI, find the **`read_pdf`** tool in the left sidebar
2. Click on it to expand the tool interface
3. Enter the parameters:
```json
{
"filePath": "C:/path/to/your/document.pdf",
"includeMetadata": true
}
```
4. Click **"Call Tool"**
5. View the response in the right panel
#### Example: Search for text
1. Select the **`search_pdf`** tool
2. Enter parameters:
```json
{
"filePath": "C:/path/to/your/document.pdf",
"searchTerm": "important keyword",
"caseSensitive": false
}
```
3. Click **"Call Tool"** and review the search results with context
#### Example: Extract an image
1. First, call **`list_pdf_images`** to discover images:
```json
{
"filePath": "C:/path/to/your/document.pdf"
}
```
2. Note the index of the image you want (e.g., `index: 0`)
3. Call **`extract_pdf_image`** with that index:
```json
{
"filePath": "C:/path/to/your/document.pdf",
"imageIndex": 0
}
```
4. The response will include Base64-encoded image data ready for decoding and saving
### Troubleshooting Inspector Issues
- **Port already in use:** Change the port with `mcp-inspector --port 5174`
- **Connection refused:** Ensure the MCP server is running before starting the Inspector
- **Tool not appearing:** Verify the tool definition in `src/index.ts` and rebuild with `npm run build`
---
## Development
### Build
```bash
npm run build
```
### Watch Mode
```bash
npm run dev
```
### Run Tests
```bash
npm test
```
**Note:** Tests require a sample PDF at `test-files/sample.pdf`. Create one or skip PDF-dependent tests.
### Watch Tests
```bash
npm run test:watch
```
### Project Structure
```
mcp-pdf-reader/
├── src/
│ ├── index.ts # MCP server implementation & tool definitions
│ ├── pdf-tools.ts # Core PDF manipulation functions
│ ├── types.ts # TypeScript interfaces & types
│ └── __tests__/
│ └── pdf-tools.test.ts # Unit tests
├── dist/ # Compiled JavaScript (generated)
├── test-files/ # Test PDF files
├── package.json
├── tsconfig.json
└── README.md
```
### Technology Stack
- **@modelcontextprotocol/sdk** (^1.25.2) - MCP protocol implementation
- **pdf-parse** (^2.4.5) - PDF text extraction
- **pdf-lib** (^1.17.1) - PDF image extraction
- **TypeScript** (^5.9.3) - Type-safe development
- **Jest** (^29.7.0) - Unit testing
---
## Limitations
- **No OCR:** Only extracts selectable text from PDFs (not scanned images)
- **Text-based PDFs:** Works best with PDFs containing embedded text. Scanned documents without OCR cannot be read
- **Image extraction:** Standard formats only (JPEG, PNG, TIFF)
- **Base64 encoding:** All images are returned as Base64 strings; large images may result in large responses
- **No PDF modification:** This server is read-only; it cannot edit or create PDFs
---
## Configuration Files
- [CLAUDE_CONFIG.md](CLAUDE_CONFIG.md) - Claude Desktop configuration guide
- [COPILOT_CONFIG.md](COPILOT_CONFIG.md) - GitHub Copilot setup instructions
---
## License
MIT - See LICENSE file for details
## Repository
[github.com/rturv/mcp-pdf-reader](https://github.com/rturv/mcp-pdf-reader)
