# 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.
## System Requirements
- Python 3.10+
- `uv` for environment and package management (recommended)
## Quick Start
1. Clone the repository and enter the directory:
```bash
git clone https://github.com/zicez/mcp-pdf2md.git
cd mcp-pdf2md
```
2. Install dependencies with uv:
```bash
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:
```bash
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:
```bash
uv run pdf2md --output-dir /path/to/my/output
```
## Claude Desktop Configuration
Add the following configuration in Claude Desktop:
**Windows**:
```json
{
"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**:
```json
{
"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](https://console.mistral.ai/) 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](https://docs.mistral.ai/api/#tag/ocr).
