# Directory Structure
```
├── Dockerfile
├── README.md
├── requirements.txt
└── src
└── server.py
```
# Files
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
# PDF Reader MCP Server
A Model Context Protocol (MCP) server that provides tools for reading and extracting text from PDF files, supporting both local files and URLs.
## Author
Philip Van de Walker
Email: [email protected]
GitHub: https://github.com/trafflux
## Features
- Read text content from local PDF files
- Read text content from PDF URLs
- Error handling for corrupt or invalid PDFs
- Volume mounting for accessing local PDFs
- Auto-detection of PDF encoding
- Standardized JSON output format
## Installation
1. Clone the repository:
```bash
git clone https://github.com/trafflux/pdf-reader-mcp.git
cd pdf-reader-mcp
```
2. Build the Docker image:
```bash
docker build -t mcp/pdf-reader .
```
## Usage
### Running the Server
To run the server with access to local PDF files:
```bash
docker run -i --rm -v /path/to/pdfs:/pdfs mcp/pdf-reader
```
Replace `/path/to/pdfs` with the actual path to your PDF files directory.
If not using local PDF files:
```bash
docker run -i --rm mcp/pdf-reader
```
### MCP Configuration
Add to your MCP settings configuration:
```json
{
"mcpServers": {
"pdf-reader": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v",
"/path/to/pdfs:/pdfs",
"mcp/pdf-reader"
],
"disabled": false,
"autoApprove": []
}
}
}
```
Without local file PDF files:
```json
{
"mcpServers": {
"pdf-reader": {
"command": "docker",
"args": ["run", "-i", "--rm", "mcp/pdf-reader"],
"disabled": false,
"autoApprove": []
}
}
}
```
### Available Tools
1. `read_local_pdf`
- Purpose: Read text content from a local PDF file
- Input:
```json
{
"path": "/pdfs/document.pdf"
}
```
- Output:
```json
{
"success": true,
"data": {
"text": "Extracted content..."
}
}
```
2. `read_pdf_url`
- Purpose: Read text content from a PDF URL
- Input:
```json
{
"url": "https://example.com/document.pdf"
}
```
- Output:
```json
{
"success": true,
"data": {
"text": "Extracted content..."
}
}
```
## Error Handling
The server handles various error cases with clear error messages:
- Invalid or corrupt PDF files
- Missing files
- Failed URL requests
- Permission issues
- Network connectivity problems
Error responses follow the format:
```json
{
"success": false,
"error": "Detailed error message"
}
```
## Dependencies
- Python 3.11+
- PyPDF2: PDF parsing and text extraction
- requests: HTTP client for fetching PDFs from URLs
- MCP SDK: Model Context Protocol implementation
## Project Structure
```
.
├── Dockerfile # Container configuration
├── README.md # This documentation
├── requirements.txt # Python dependencies
└── src/
├── __init__.py # Package initialization
└── server.py # Main server implementation
```
## License
Copyright 2025 Philip Van de Walker
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Contact
For questions, issues, or contributions, please contact Philip Van de Walker:
- Email: [email protected]
- GitHub: https://github.com/trafflux
```
--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
```
PyPDF2>=3.0.0
requests>=2.31.0
```
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
```dockerfile
# PDF Reader MCP Server Dockerfile
# Author: Philip Van de Walker
# Email: [email protected]
# Repo: https://github.com/trafflux/pdf-reader-mcp
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# Use Python 3.11 slim image as base
FROM python:3.11-slim
# Set working directory
WORKDIR /app
# Install git for MCP SDK installation
RUN apt-get update && \
apt-get install -y git && \
apt-get clean && \
rm -rf /var/lib/apt/lists/*
# Install MCP SDK directly from GitHub repository
RUN pip install git+https://github.com/modelcontextprotocol/python-sdk.git
# Install project Python dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt
# Copy source code into container
COPY src/ .
# Command to run the server
# The container expects a volume mount at /pdfs for accessing local PDF files
ENTRYPOINT ["python", "server.py"]
```
--------------------------------------------------------------------------------
/src/server.py:
--------------------------------------------------------------------------------
```python
"""
PDF Reader MCP Server
--------------------
A Model Context Protocol (MCP) server that provides tools for reading and extracting text from PDF files.
Supports both local files and URLs, with comprehensive error handling and standardized output format.
Author: Philip Van de Walker
Email: [email protected]
Repo: https://github.com/trafflux/pdf-reader-mcp
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
This module implements an MCP server with two main tools:
- read_local_pdf: Extracts text from local PDF files
- read_pdf_url: Extracts text from PDFs accessed via URLs
The server uses FastMCP for simplified tool registration and standardized error handling.
All text extraction is done using PyPDF2 with proper error handling for various edge cases.
"""
import os
import io
import logging
from typing import Dict, Any
import PyPDF2
import requests
from mcp.server.fastmcp import FastMCP
def get_logger(name: str):
logger = logging.getLogger(name)
return logger
logger = get_logger(__name__)
# Create server instance using FastMCP
mcp = FastMCP("pdf-reader")
def extract_text_from_pdf(pdf_file) -> str:
"""Extract text content from a PDF file."""
try:
reader = PyPDF2.PdfReader(pdf_file)
text = ""
for page in reader.pages:
text += page.extract_text() + "\n"
return text.strip()
except Exception as e:
logger.error(f"Failed to extract text from PDF: {str(e)}")
raise ValueError(f"Failed to extract text from PDF: {str(e)}")
@mcp.tool()
async def read_local_pdf(path: str) -> Dict[str, Any]:
"""Read text content from a local PDF file."""
try:
with open(path, 'rb') as file:
text = extract_text_from_pdf(file)
return {
"success": True,
"data": {
"text": text
}
}
except FileNotFoundError:
logger.error(f"PDF file not found: {path}")
return {
"success": False,
"error": f"PDF file not found: {path}"
}
except Exception as e:
logger.error(str(e))
return {
"success": False,
"error": str(e)
}
@mcp.tool()
async def read_pdf_url(url: str) -> Dict[str, Any]:
"""Read text content from a PDF URL."""
try:
response = requests.get(url)
response.raise_for_status()
pdf_file = io.BytesIO(response.content)
text = extract_text_from_pdf(pdf_file)
return {
"success": True,
"data": {
"text": text
}
}
except requests.RequestException as e:
logger.error(f"Failed to fetch PDF from URL: {str(e)}")
return {
"success": False,
"error": f"Failed to fetch PDF from URL: {str(e)}"
}
except Exception as e:
logger.error(str(e))
return {
"success": False,
"error": str(e)
}
def main() -> None:
"""Run the MCP server."""
try:
mcp.run()
except Exception as e:
logger.error(f"Error starting server: {str(e)}")
raise
if __name__ == "__main__":
main()
```