PDF to Markdown Converter MCP server

This MCP-PDF2MD server provides high-performance PDF to Markdown conversion using the MinerU API, supporting both local PDF files and URL links with intelligent structure preservation.

Installation

Prerequisites

• Python 3.10 or newer

Setup Instructions

1. Clone the repository and navigate to the project directory:

   git clone https://github.com/FutureUnreal/mcp-pdf2md.git
   cd mcp-pdf2md
   

2. Create and activate a virtual environment:

   Linux/macOS:

   uv venv
   source .venv/bin/activate
   uv pip install -e .
   

   Windows:

   uv venv
   .venv\Scripts\activate
   uv pip install -e .
   

3. Configure the MinerU API:

   Create a .env file in the project root with the following content:

   MINERU_API_BASE=https://mineru.net/api/v4/extract/task
   MINERU_BATCH_API=https://mineru.net/api/v4/extract/task/batch
   MINERU_BATCH_RESULTS_API=https://mineru.net/api/v4/extract-results/batch
   MINERU_API_KEY=your_api_key_here
   

4. Start the service:

   uv run pdf2md
   

Using with Claude Desktop

Configuration

Add the MCP server configuration to Claude Desktop:

Windows:

{
    "mcpServers": {
        "pdf2md": {
            "command": "uv",
            "args": [
                "--directory",
                "C:\\path\\to\\mcp-pdf2md",
                "run",
                "pdf2md",
                "--output-dir",
                "C:\\path\\to\\output"
            ],
            "env": {
                "MINERU_API_KEY": "your_api_key_here"
            }
        }
    }
}

Linux/macOS:

{
    "mcpServers": {
        "pdf2md": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/mcp-pdf2md",
                "run",
                "pdf2md",
                "--output-dir",
                "/path/to/output"
            ],
            "env": {
                "MINERU_API_KEY": "your_api_key_here"
            }
        }
    }
}

API Key Setup

You can configure the API key in either:

• The .env file (for development)
• The Claude Desktop configuration (for regular use)

The configuration in Claude Desktop takes precedence if both are set.

Available MCP Tools

The server provides two main tools:

• convert_pdf_url: Converts PDFs from URLs to Markdown
• convert_pdf_file: Converts local PDF files to Markdown

Getting a MinerU API Key

To obtain the required API key:

1. Register an account at MinerU
2. Apply for API testing qualification at this page
3. After approval, go to API Management
4. Generate your API key following their instructions
5. Add this key to your configuration

Note that MinerU API access requires approval and may take some time to process.

Key Features

• Converts PDFs to structured Markdown
• Supports both local files and URL links
• Maintains document structure (headings, paragraphs, lists)
• Handles single-column, multi-column, and complex layouts
• Converts formulas to LaTeX format
• Extracts tables into structured format
• Removes headers, footers, page numbers for better output
• Supports batch processing for multiple files

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.