xxx87/pdf-to-text-mcp

📄 PDF to Text MCP Server

A Model Context Protocol (MCP) server for converting PDF files to text, designed for seamless integration with Cursor IDE and other MCP-compatible applications.

🚀 Quick Start

# Clone the repository
git clone https://github.com/xxx87/pdf-to-text-mcp.git
cd pdf-to-text-mcp-server

# Install dependencies
yarn install

# Build the project
yarn build

# Test the server
yarn test

✨ Features

• 📑 Multi-file Support - Convert one or multiple PDF files simultaneously
• 🔍 Text Extraction - Extract text while preserving document structure
• ⚡ Fast Processing - Efficient PDF parsing with pdf-parse library
• 🔧 MCP Protocol - Full Model Context Protocol compliance
• 🎯 Cursor Integration - Designed specifically for Cursor IDE
• 🛡️ TypeScript - Fully typed for better development experience
• ✅ Testing - Comprehensive test suite included

📋 Table of Contents

• Installation
• Usage
• Configuration
• API Reference
• Development
• Troubleshooting
• Contributing
• License

🛠️ Installation

Prerequisites

• Node.js 18+
• Yarn package manager
• Cursor IDE (for MCP integration)

Local Installation

1. Clone the repository

   git clone https://github.com/xxx87/pdf-to-text-mcp.git
   cd pdf-to-text-mcp-server
   

2. Install dependencies

   yarn install
   

3. Build the project

   yarn build
   

4. Verify installation

   yarn test
   

🎯 Usage

Running as Standalone Server

yarn start

Integration with Cursor IDE

1. Add to Cursor Configuration

   Add the following to your Cursor MCP settings:

   {
     "mcpServers": {
       "pdf-to-text": {
         "command": "node",
         "args": ["/absolute/path/to/pdf-to-text-mcp-server/dist/index.js"],
         "cwd": "/absolute/path/to/pdf-to-text-mcp-server"
       }
     }
   }
   

   ⚠️ Important: Replace /absolute/path/to/pdf-to-text-mcp-server with your actual project path.

2. Using in Cursor

   • Add PDFs: Drag and drop PDF files into Cursor
   • Convert: Use the pdf_to_text tool for automatic conversion
   • Analyze: The extracted text becomes available for AI analysis

Manual MCP Usage

// Example MCP JSON-RPC request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pdf_to_text",
    "arguments": {
      "file_paths": ["document1.pdf", "document2.pdf"]
    }
  }
}

⚙️ Configuration

Environment Variables

Custom Options

The server automatically handles PDF parsing with optimized settings. For custom configurations, modify the pdf-parse options in src/index.ts.

📚 API Reference

Tools

pdf_to_text

Converts PDF files to readable text format.

Parameters:

• file_paths (string[]): Array of PDF file paths to convert

Returns:

{
  content: [
    {
      type: "text",
      text: string // Extracted text with file separators
    }
  ];
}

Example Response:

{
  "content": [
    {
      "type": "text",
      "text": "Successfully converted 2 PDF file(s) to text:\n\n=== document1.pdf ===\nExtracted content here...\n\n=== document2.pdf ===\nMore content here..."
    }
  ]
}

🏗️ Development

Project Structure

pdf-to-text-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   └── types/
│       └── pdf-parse.d.ts    # Type definitions
├── dist/                     # Compiled JavaScript output
├── test-server.js            # Test utilities
├── package.json              # Project configuration
├── tsconfig.json             # TypeScript configuration
├── cursor-config.json        # Example Cursor configuration
└── README.md                 # This file

Available Scripts

Building from Source

# Development mode with file watching
yarn dev

# Production build
yarn build

# Run tests
yarn test

Dependencies

🐛 Troubleshooting

Common Issues

Debug Mode

Enable verbose logging:

NODE_ENV=development yarn start

Testing

Run the comprehensive test suite:

# Run all tests
yarn test

# Test with specific PDF
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "pdf_to_text", "arguments": {"file_paths": ["your-file.pdf"]}}}' | node dist/index.js

🤝 Contributing

We welcome contributions! Please see our for details.

Development Setup

1. Fork the repository
2. Clone your fork
3. Create a feature branch: git checkout -b feature/amazing-feature
4. Make your changes
5. Test thoroughly: yarn test
6. Commit changes: git commit -m 'Add amazing feature'
7. Push to branch: git push origin feature/amazing-feature
8. Open a Pull Request

Code Style

• Follow existing TypeScript conventions
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Model Context Protocol for the excellent MCP specification
• pdf-parse for reliable PDF text extraction
• Cursor IDE for MCP integration support

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki