# MCP PDF Reader Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude, Windsurf, and other MCP-compatible tools to read and analyze PDF files.

## Features

- 📄 Read PDF files from **local paths or URLs**
- 🔍 Search for specific terms within PDFs
- 📊 Get PDF metadata (page count, author, title, etc.)
- 📖 Read specific pages or page ranges
- 🌐 Download and analyze PDFs from the web
- 🤖 Seamless integration with AI assistants via MCP

## Installation

### Using npm

```bash
npm install -g @dev.saqibaziz/mcp-pdf-reader
```

### Using npx (no installation required)

```bash
npx @dev.saqibaziz/mcp-pdf-reader
```

## Configuration

### For Claude Desktop

Add this to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["-y", "@dev.saqibaziz/mcp-pdf-reader"]
    }
  }
}
```

### For Windsurf

**Option 1: Via Plugin Store (Coming Soon)**

- Open Windsurf
- Click the `Plugins` icon in Cascade panel
- Search for "PDF Reader"
- Click `Install`

**Option 2: Manual Configuration**

Edit your MCP configuration file:

**macOS**: `~/Library/Application Support/Windsurf/User/globalStorage/codeium.codeium/mcp_config.json`
**Windows**: `%APPDATA%\Windsurf\User\globalStorage\codeium.codeium\mcp_config.json`
**Linux**: `~/.config/Windsurf/User/globalStorage/codeium.codeium/mcp_config.json`

```json
{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["-y", "@dev.saqibaziz/mcp-pdf-reader"]
    }
  }
}
```

After adding, click the refresh button in the Plugins panel.

### For Cline

Add this to your MCP settings file:

```json
{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["-y", "@dev.saqibaziz/mcp-pdf-reader"]
    }
  }
}
```

## Available Tools

The server provides the following tools to AI assistants:

### `read_pdf_pages`

Read specific pages from a PDF file.

**Parameters:**

- `pdf_path` (string): Path to the PDF file
- `pages` (array): List of page numbers to read

### `read_pdf_page_range`

Read a range of pages from a PDF file.

**Parameters:**

- `pdf_path` (string): Path to the PDF file
- `start_page` (number): First page to read (inclusive)
- `end_page` (number): Last page to read (inclusive)

### `search_pdf`

Search for terms in a PDF file and return pages containing them.

**Parameters:**

- `pdf_path` (string): Path to the PDF file
- `terms` (string or array): Search term(s)

### `get_pdf_metadata`

Get metadata from a PDF file (page count, author, title, etc.).

**Parameters:**

- `pdf_path` (string): Path to the PDF file

## Usage Examples

Once configured, you can ask your AI assistant:

**Local Files:**
- "Read pages 1-5 from document.pdf"
- "Search for 'machine learning' in research.pdf"
- "What's the metadata of report.pdf?"
- "Read page 10 from presentation.pdf"

**URLs:**
- "Read this PDF: https://example.com/research-paper.pdf"
- "Search for 'climate change' in https://example.com/report.pdf"
- "Get metadata from https://arxiv.org/pdf/2301.00001.pdf"
- "Read pages 1-3 from https://example.com/whitepaper.pdf"

## Development

### Prerequisites

- Node.js >= 18.0.0
- npm or yarn

### Setup

```bash
# Clone the repository
git clone https://github.com/Saqib-Aziz007/mcp-pdf-reader.git
cd mcp-pdf-reader

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev
```

### Scripts

- `npm run build` - Compile TypeScript to JavaScript
- `npm run dev` - Watch mode for development
- `npm start` - Run the compiled server
- `npm run prepare` - Pre-install build hook

## Technical Details

This MCP server is built with:

- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) - MCP SDK for TypeScript
- [pdf-parse](https://www.npmjs.com/package/pdf-parse) - PDF parsing library
- TypeScript for type safety

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see [LICENSE](LICENSE) file for details

## Author

**Muhammad Saqib Aziz**

- Email: saqib.aziz1000@gmail.com
- GitHub: [@Saqib-Aziz007](https://github.com/Saqib-Aziz007)
- npm: [@saqibaziz](https://www.npmjs.com/~dev.saqibaziz)

## Support

If you encounter any issues or have questions:

- Open an issue on [GitHub](https://github.com/Saqib-Aziz007/mcp-pdf-reader/issues)
- Check the [MCP documentation](https://modelcontextprotocol.io/)

## Acknowledgments

Built with the Model Context Protocol by Anthropic.