How do I use MCP-PDF2MD?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP-PDF2MD convert this PDF from https://example.com/report.pdf to markdown" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP-PDF2MD

by zicez

Overview Schema Source Related Servers Score Discussions Admin

Python

Hybrid

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

Clone the repository and enter the directory:

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

Install dependencies with uv:
```
uv sync
```
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
```
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:

In the .env file within the project directory (recommended for development).
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:

Visit the Mistral AI Platform and create an account.
Navigate to the "API Keys" section in your workspace.
Create a new secret key.
Copy the generated API key.
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.

ParametersJSON Schema

Name	Required	Description	Default
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the conversion process, output format (Markdown), and storage behavior (saved in a new folder), but doesn't mention error handling, performance characteristics, file size limits, or permission requirements. It provides basic operational context but lacks comprehensive behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with three focused sentences: purpose statement, parameter explanation, and return value description. Each sentence adds distinct value without redundancy. The information is front-loaded with the core functionality stated first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (file conversion with storage implications), no annotations, and an output schema present, the description covers the essential operations well. It explains what the tool does, parameter usage, and mentions the return format (though output schema handles details). However, it could better address error cases or limitations given the file system operations involved.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must fully compensate. It explains the 'file_path' parameter meaningfully, specifying it accepts 'a local PDF file or multiple paths separated by spaces, commas, or newlines,' which adds crucial semantic information beyond the schema's basic type declaration. However, it doesn't detail path format requirements or validation rules.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Convert a local PDF file to Markdown') and the resource ('PDF file'), distinguishing it from the sibling tool 'convert_pdf_url' which handles URLs rather than local files. The description explicitly mentions the output format and storage location, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool (for local PDF files) versus the sibling tool (for URLs), though it doesn't explicitly state 'when not to use' or mention alternative tools beyond the sibling. The guidance is sufficient to differentiate use cases but lacks explicit exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the conversion output is saved to a directory (--output-dir), and it handles multiple URLs. However, it misses details like error handling, rate limits, authentication needs, or file format specifics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the core purpose, followed by specific sections for Args and Returns. Every sentence adds value without redundancy, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (conversion with output handling), no annotations, and an output schema present, the description is mostly complete. It covers purpose, parameters, and output behavior, but lacks some contextual details like prerequisites or error scenarios that could enhance agent understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It adds meaningful semantics: the 'url' parameter can be a single URL or multiple URLs separated by spaces, commas, or newlines, which clarifies usage beyond the basic schema. It doesn't detail URL validation or examples, keeping it from a perfect score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: converting PDFs from URLs to Markdown with specific output behavior. It uses precise verbs ('Convert', 'saved') and distinguishes from the sibling tool convert_pdf_file by specifying URL-based input rather than file-based input.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly indicates when to use this tool (for URL-based PDF conversion) versus the sibling convert_pdf_file (for file-based conversion). However, it lacks explicit guidance on when not to use it or detailed alternatives beyond the sibling tool name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

2 tool updatesDec 31, 2025
- First observedconvert_pdf_file
- First observedconvert_pdf_url

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0

Scored 2026-04-18 07:30 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.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Brainiall Documents A
com.brainiall
High-fidelity PDF to structured Markdown conversion and document field extraction.
Data Platforms
31
agentmd A
io.github.djrobson5
Convert PDF, DOCX, HTML, and URLs to clean, LLM-ready markdown with tables preserved
Documentation Access Web Scraping
21
file2markdown A
ai.file2markdown
Convert documents and web pages to clean Markdown: PDF, DOCX, XLSX, EPUB, scanned files, any URL.
Browser Automation Documentation Access Web Scraping
41
PDF Text, Table and OCR ExtractorOAuth
io.github.brenton-keller
PDF URLs to per-page text, tables as rows, Markdown, metadata and OCR for scanned pages.
Data Platforms Research & Data
1

Related MCP Servers

Lizeur
Developer Tools App Automation
SilverBzH
A
license
B
quality
D
maintenance
Enables AI assistants to extract and read content from PDF documents using Mistral AI's OCR capabilities. Provides intelligent caching and returns clean markdown text for easy integration with AI workflows.
Updated a year ago (2025-08-23 04:40 UTC)
2
1
MIT
PDF Reader MCP Server
File Systems Documentation Access Text Summarization
rexfelix
F
license
A
quality
D
maintenance
Enables reading and extracting content from PDF documents including text (as Markdown), images, tables, and metadata from both local files and URLs, with OCR support for scanned documents.
Updated 9 months ago (2025-12-13 11:16 UTC)
2
-
MinerU Document to Markdown
Documentation Access File Systems Developer Tools
AvatarGanymede
A
license
B
quality
D
maintenance
Converts documents (PDF, Word, PPT, images, HTML) to Markdown via MinerU API. Supports URL and local file inputs with OCR, formula/table recognition, and automatic large file handling.
Updated 6 months ago (2026-02-27 05:42 UTC)
5
5
MIT
DocMistral MCP Server
AI & Machine Learning Image & Video Processing Documentation Access
trsdn
A
license
Not graded
quality
A
maintenance
Converts documents and images to Markdown using Mistral AI's OCR, enabling AI-powered document processing via MCP-compatible clients like Claude Desktop.
Updated 7 days ago (2026-09-03 14:36 UTC)
274
2
MIT

MCP-PDF2MD

MCP-PDF2MD Service

Key Features

System Requirements

Quick Start

Command Line Arguments

Claude Desktop Configuration

MCP Tools

Getting a Mistral AI API Key

License

Credits

Available Tools

Output Schema

TDQS

Output Schema

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Lizeur

PDF Reader MCP Server

MinerU Document to Markdown

DocMistral MCP Server