mcp-pdf-reader

# 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.