document-converter

# 📄 Document Converter MCP

<p align="center">
  <strong>Convert documents to Markdown inside Cursor, VS Code, and any MCP client.</strong><br>
  Local processing · No cloud upload · Powered by <a href="https://github.com/microsoft/markitdown">MarkItDown</a>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+"></a>
  <a href="https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Zahid-Abbas-Ali-Baig%2Fdocument-converter/versions/1.0.0"><img src="https://img.shields.io/badge/MCP-Registry-green.svg" alt="MCP Registry"></a>
</p>

Give your AI assistant the ability to **read PDFs, Office files, spreadsheets, emails, audio, and more** as clean Markdown — so it can summarize, search, and reason over content instead of struggling with binary attachments.

---

## Table of contents

- [Overview 📋](#overview-)
- [Use cases 💡](#use-cases-)
- [Features ✨](#features-)
- [Supported formats 📎](#supported-formats-)
- [Quick install 🚀](#quick-install-)
  - [Before you start](#before-you-start-all-editors)
  - [Cursor 🖱️](#install-in-cursor)
  - [VS Code 💻](#install-in-vs-code)
  - [Claude Desktop 🤖](#install-in-claude-desktop)
  - [Verify it works ✅](#verify-it-works)
- [Tools 🛠️](#tools-)
- [Usage examples 💬](#usage-examples-)
- [Local development 🧪](#local-development-)
- [Configuration reference ⚙️](#configuration-reference-)
- [MCP Registry 📦](#mcp-registry-)
- [Troubleshooting 🔧](#troubleshooting-)
- [License 📜](#license-)

---

## Overview 📋

**Document Converter MCP** is a lightweight stdio server that wraps Microsoft's [MarkItDown](https://github.com/microsoft/markitdown) library for the [Model Context Protocol](https://modelcontextprotocol.io).

```mermaid
flowchart LR
  A[Your file on disk] --> B[Document Converter MCP]
  B --> C[MarkItDown]
  C --> D[Markdown in chat or .md file]
```

| | |
|---|---|
| **Registry** | [`io.github.Zahid-Abbas-Ali-Baig/document-converter`](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Zahid-Abbas-Ali-Baig%2Fdocument-converter/versions/1.0.0) |
| **Repository** | [https://github.com/Zahid-Abbas-Ali-Baig/document-converter](https://github.com/Zahid-Abbas-Ali-Baig/document-converter) |
| **Transport** | stdio |
| **Author** | Zahid Abbas Ali Baig |
| **Dependencies** | `markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]` |

Once connected, your agent converts files locally and returns structured text — nothing is sent to a conversion API.

---

## Use cases 💡

| Scenario | What you gain |
|----------|----------------|
| **Research** | Turn PDF papers into Markdown, then ask for summaries, comparisons, or citations |
| **Documentation** | Convert `.docx` / `.pptx` drafts into `.md` beside the source for wikis or Git |
| **Product & engineering** | Preview specs and slide decks in chat before writing tickets or release notes |
| **Data & ops** | Convert Excel exports into tables the model can filter, explain, or transform |
| **Email & archives** | Extract text from `.msg` Outlook files or ZIP contents without manual copy-paste |
| **Media** | Transcribe `.mp3` / `.wav` or fetch YouTube captions into editable Markdown |

---

## Features ✨

- 🏠 **Local-first** — files stay on your machine; no third-party conversion service
- 📎 **Broad format coverage** — PDF, Office, CSV/JSON/text, Outlook `.msg`, audio, YouTube, and more (via MarkItDown)
- 🔀 **Two workflows** — save Markdown next to the source, or preview in chat only
- 📋 **Copy-paste setup** — step-by-step install for Cursor, VS Code, and Claude Desktop
- 📦 **Registry published** — listed on the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Zahid-Abbas-Ali-Baig%2Fdocument-converter/versions/1.0.0)
- ⚖️ **MIT licensed** — free for personal and commercial use

---

## Supported formats 📎

Formats below are verified against [MarkItDown](https://github.com/microsoft/markitdown) **0.1.6** with our installed extras:

`markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]`

We avoid `markitdown[all]` because it pulls Azure pre-release packages that `uv` cannot resolve with `uvx`.

### Fully supported (with this project's dependencies)

| Category | Extensions / inputs | What you get |
|----------|---------------------|--------------|
| **PDF** | `.pdf` | Text and layout extraction (`[pdf]` extra) |
| **Word** | `.docx` only | Headings, paragraphs, tables (`[docx]` — not legacy `.doc`) |
| **PowerPoint** | `.pptx` only | Slide text and structure (`[pptx]` — not legacy `.ppt`) |
| **Excel** | `.xlsx`, `.xls` | Workbook tables (`[xlsx]` / `[xls]`) |
| **Outlook** | `.msg` | Headers, body, metadata (`[outlook]`) |
| **Web** | `.html`, `.htm` | HTML → Markdown (built-in) |
| **CSV** | `.csv` | Markdown tables (built-in) |
| **Text & JSON** | `.txt`, `.md`, `.json`, `.jsonl` | Plain text / JSON content (built-in) |
| **Notebooks** | `.ipynb` | Notebook cells as Markdown (built-in) |
| **E-books** | `.epub` | Chapter HTML → Markdown (built-in) |
| **Archives** | `.zip` | Each inner file converted if its type is supported (built-in) |
| **Audio** | `.mp3`, `.wav`, `.m4a` | Metadata + speech transcription (`[audio-transcription]`) |
| **YouTube** | `https://www.youtube.com/watch?v=...` | Title, description, captions when available (`[youtube-transcription]`) |

### Limited support

| Category | Extensions | Reality |
|----------|------------|---------|
| **Images** | `.jpg`, `.jpeg`, `.png` only | EXIF metadata if `exiftool` is on your PATH; **no built-in OCR** in this MCP server (MarkItDown can describe images only when an LLM client is configured, which we do not set up) |
| **XML** | `.xml` | May work as plain text depending on file detection — not a dedicated XML parser |
| **Other URLs** | Wikipedia, RSS, Bing SERP | MarkItDown can fetch some web URLs; not tested as part of this MCP |

### Not supported

| Item | Why |
|------|-----|
| **`.eml`** | No MarkItDown converter for RFC 822 `.eml` files |
| **`.gif`, `.webp`, `.bmp`, …** | Image converter only accepts `.jpg` / `.jpeg` / `.png` |
| **Legacy Office** | `.doc`, `.ppt` — use `.docx` / `.pptx` |
| **Video files** | `.mp4` etc. — not converted as video (audio track may work in some cases via the audio converter) |
| **Azure Document Intelligence** | Needs `markitdown[az-doc-intel]` + Azure endpoint |
| **Azure Content Understanding** | Pre-release package; breaks `uvx` resolution |
| **`markitdown[all]`** | Bundles the Azure extras above |

Conversion quality depends on the source file. See the [MarkItDown documentation](https://github.com/microsoft/markitdown) for upstream details.

---

## Quick install 🚀

Follow the steps for your editor. Every config below uses the same command — only the JSON file and wrapper key differ.

### Before you start (all editors)

1. **Install [uv](https://docs.astral.sh/uv/getting-started/installation/)** (includes `uvx`).

   **Windows (PowerShell):**
   ```powershell
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   ```

   **macOS / Linux:**
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

2. **Verify `uvx` works** (open a **new** terminal after installing):

   ```bash
   uvx --version
   ```

3. **Optional — test the server** (it will sit idle with no output; that is normal for stdio MCP):

   ```bash
   uvx --from git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter --with markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription] document-converter-mcp
   ```

   Press `Ctrl+C` to stop.

---

<a id="install-in-cursor"></a>

### Install in Cursor 🖱️

1. Open **Cursor → Settings → MCP** (or edit your config file directly).
2. **Config file location:**
   - **Windows:** `%USERPROFILE%\.cursor\mcp.json`
   - **macOS:** `~/.cursor/mcp.json`
   - **Linux:** `~/.cursor/mcp.json`
   - **Project-only:** `.cursor/mcp.json` in your project folder
3. Add or merge this block inside `mcpServers` (copy the whole JSON):

```json
{
  "mcpServers": {
    "document-converter": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter",
        "--with",
        "markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]",
        "document-converter-mcp"
      ]
    }
  }
}
```

4. **Save** the file and **restart Cursor** (or click **Reload** next to MCP in settings).
5. **Check:** Settings → MCP → `document-converter` should show **enabled** (green). Tools: `convert_to_markdown`, `preview_markdown`.

<details>
<summary>Cursor one-click install (optional — if manual JSON fails, use this)</summary>

1. Open this link in your browser: [**Add to Cursor**](https://cursor.com/en/install-mcp?name=document-converter&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJnaXQraHR0cHM6Ly9naXRodWIuY29tL1phaGlkLUFiYmFzLUFsaS1CYWlnL2RvY3VtZW50LWNvbnZlcnRlciIsIi0td2l0aCIsIm1hcmtpdGRvd25bcGRmLGRvY3gscHB0eCx4bHN4LHhscyxvdXRsb29rLGF1ZGlvLXRyYW5zY3JpcHRpb24seW91dHViZS10cmFuc2NyaXB0aW9uXSIsImRvY3VtZW50LWNvbnZlcnRlci1tY3AiXX0%3D)
2. Or paste into the browser address bar:

```
cursor://anysphere.cursor-deeplink/mcp/install?name=document-converter&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJnaXQraHR0cHM6Ly9naXRodWIuY29tL1phaGlkLUFiYmFzLUFsaS1CYWlnL2RvY3VtZW50LWNvbnZlcnRlciIsIi0td2l0aCIsIm1hcmtpdGRvd25bcGRmLGRvY3gscHB0eCx4bHN4LHhscyxvdXRsb29rLGF1ZGlvLXRyYW5zY3JpcHRpb24seW91dHViZS10cmFuc2NyaXB0aW9uXSIsImRvY3VtZW50LWNvbnZlcnRlci1tY3AiXX0%3D
```

3. Click **Install** in Cursor, then restart if tools do not appear.

</details>

---

<a id="install-in-vs-code"></a>

### Install in VS Code 💻

Requires **VS Code 1.102+** with [built-in MCP supp