MCP-PDF2MD Service

Provides MCP-based PDF to Markdown conversion with batch support for local files and URLs using Mistral OCR.

python

1

GitHub Stars

python

Language

5 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "zicez-mcp-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"
      }
    }
  }
}

You can run MCP-PDF2MD as a focused, high-performance service to convert PDF documents to Markdown, with support for both local files and remote URLs. It preserves structure, extracts images, and integrates with MCP-enabled clients for streamlined workflows.

How to use

To convert PDFs via an MCP client, use the provided functions to transform either a URL or a local file into structured Markdown. The service outputs include preserved headings, paragraphs, lists, and extracted images saved to your chosen directory. Use the functions to batch process multiple inputs in a single call.

How to install

Prerequisites: Python 3.10+ and uvx for environment and package management.

Clone the project and enter the directory.

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

Install dependencies with uvx.

uv sync

Create an environment file and set your Mistral AI API key.

# Linux/macOS
echo "MISTRAL_API_KEY=your_mistral_api_key_here" > .env

# Windows PowerShell
echo `"MISTRAL_API_KEY=your_mistral_api_key_here`" > .env

Start the service.

uv run pdf2md

Additional configuration and usage notes

Command line arguments support customizing the output directory where converted Markdown files and images are saved. The default output directory is ./downloads, but you can specify a different path when starting the service.

Environment variables can be configured in two places. The recommended approach is to store MISTRAL_API_KEY in a .env file at the project root. You can also set it in the MCP client configuration if you run the service through an MCP client that injects environment variables. If both are set, the client configuration takes precedence.

Usage via MCP clients

When you use an MCP client, call the provided tools to convert PDFs from either a URL or a local file path. For a URL, pass the URL string to convert_pdf_url; for a local file, pass the file path to convert_pdf_file. You can supply multiple inputs separated by spaces, commas, or newlines.

Available tools

convert_pdf_url

Converts a PDF from a URL to Markdown. Accepts a single URL or multiple URLs separated by spaces, commas, or newlines.

convert_pdf_file

Converts a local PDF file to Markdown. Accepts one or more file paths separated by spaces, commas, or newlines.