Skip to main content
Glama

MCP-PDF2MD

MCP-PDF2MD Service

An MCP-based high-performance PDF to Markdown conversion service powered by the Mistral AI OCR API, supporting batch processing for local files and URL links with structured output.

Key Features

  • Format Conversion: Convert PDF files to structured Markdown format.

  • Multi-source Support: Process both local PDF files and remote PDF URLs.

  • MCP Integration: Seamlessly integrates with LLM clients like Claude Desktop.

  • Structure Preservation: Aims to maintain the original document structure, including headings, paragraphs, and lists.

  • Image Extraction: Automatically extracts images from the PDF and saves them locally.

  • High-Quality Extraction: Leverages Mistral AI's state-of-the-art OCR for high-quality text and layout information extraction.

Related MCP server: PDF Reader MCP Server

System Requirements

  • Python 3.10+

  • uv for environment and package management (recommended)

Quick Start

  1. Clone the repository and enter the directory:

    git clone https://github.com/zicez/mcp-pdf2md.git
    cd mcp-pdf2md
  2. Install dependencies with uv:

    uv sync
  3. Configure environment variables:

    Create a .env file in the project root directory and set your Mistral AI API key:

    MISTRAL_API_KEY=your_mistral_api_key_here
  4. Start the service:

    uv run pdf2md

Command Line Arguments

The server supports the following command line arguments:

  • --output-dir: Specify the directory to save converted Markdown files and images. Defaults to ./downloads.

Example:

uv run pdf2md --output-dir /path/to/my/output

Claude Desktop Configuration

Add the following configuration in Claude Desktop:

Windows:

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

Linux/macOS:

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

Note about API Key Configuration: You can set the API key in two ways:

  1. In the .env file within the project directory (recommended for development).

  2. In the Claude Desktop configuration as shown above (recommended for regular use).

If you set the API key in both places, the one in the Claude Desktop configuration will take precedence.

MCP Tools

The server provides the following MCP tools:

  • convert_pdf_url(url: str): Converts a PDF from a URL to Markdown. Supports single URLs or multiple URLs separated by spaces, commas, or newlines.

  • convert_pdf_file(file_path: str): Converts a local PDF file to Markdown. Supports single or multiple file paths separated by spaces, commas, or newlines.

Getting a Mistral AI API Key

This project relies on the Mistral AI API for PDF content extraction. To obtain an API key:

  1. Visit the Mistral AI Platform and create an account.

  2. Navigate to the "API Keys" section in your workspace.

  3. Create a new secret key.

  4. Copy the generated API key.

  5. Use this key as the value for MISTRAL_API_KEY.

License

MIT License - see the LICENSE file for details.

Credits

This project uses the Mistral AI OCR API.

Available Tools

2 tools
convert_pdf_fileA
Convert a local PDF file to Markdown. Output is saved in a new folder named after the PDF in its original directory.

Args:
    file_path: Path to a local PDF file or multiple paths separated by spaces, commas, or newlines.

Returns:
    A dictionary with the conversion results.

Inputs: file_path (required). Returns: result

convert_pdf_urlA
Convert a PDF from a URL to Markdown. The output is saved in the directory specified by --output-dir.

Args:
    url: A single PDF URL or multiple URLs separated by spaces, commas, or newlines.

Returns:
    A dictionary with the conversion results.

Inputs: url (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: one handles local PDF files, while the other handles PDFs from URLs. There is no overlap in functionality, and the descriptions explicitly differentiate between file-based and URL-based inputs, making misselection unlikely.

    Naming Consistency5/5

    Both tools follow a consistent verb_noun pattern with 'convert_pdf_' as the prefix, followed by 'file' or 'url'. This predictable naming scheme makes it easy to understand their roles and maintain consistency across the tool set.

    Tool Count3/5

    With only 2 tools, the server feels thin for a PDF conversion domain, as it lacks operations like batch processing, configuration adjustments, or error handling tools. While the core conversion is covered, the limited scope may restrict agent workflows, placing it in the borderline range.

    Completeness3/5

    The server covers the basic conversion functionality for both local files and URLs, but there are notable gaps such as no tools for managing output directories, handling conversion errors, or providing status updates. This incomplete surface could lead to agent failures in more complex scenarios.

    Related MCP Connectors

    Related MCP Servers