markitdown

Markitdown is a cloud-hosted MCP server that converts a wide range of documents into clean, AI-ready Markdown. It leverages Microsoft’s Markitdown under the hood and exposes an MCP-compatible API so clients and MCP-enabled tools can request Markdown outputs from input documents or file URLs. Typical workflows include feeding a file URL (or base64-encoded content) to the server via MCP clients or API calls, then consuming the resulting Markdown for use in knowledge bases, RAG pipelines, or AI agents. The server is designed to work seamlessly with Claude Desktop, Cursor, Aider, and other MCP-enabled tools, enabling automatic discovery and invocation of the conversion capability when a user asks for a document-to-Markdown transformation. For developers, you can call the API directly or through the Apify ecosystem to obtain the Markdown and, if needed, the accompanying metadata such as file type and length. Key capabilities include OCR-assisted extraction for images, support for 29+ formats, and fast, cloud-based processing.

Prerequisites:

• Node.js and npm (to run the MCP client wrapper via npx) or access to an MCP-enabled environment
• Access token for Apify (YOUR_APIFY_TOKEN) if you’re using the Apify-hosted endpoint

Installation steps:

1. Ensure Node.js is installed:

node -v
npm -v

2. Prepare your MCP configuration file (example shown in this doc):

• Create or edit your MCP config to point to the Markitdown MCP server (see mcp_config below).

3. Set the required environment variable for your API token (if you’re using Apify):

• On Unix-like shells:

export APIFY_TOKEN=YOUR_APIFY_TOKEN

• On Windows (PowerShell):

$Env:APIFY_TOKEN = "YOUR_APIFY_TOKEN"

4. Run or test your setup in your MCP-enabled application or tool. For Claude Desktop or other MCP clients, ensure the mcpServers entry (markitdown) is present in your client’s config (see mcp_config section).

5. Validate by sending a test request via MCP (example for API users is shown in the Quick Start of the README):

curl -X POST https://api.apify.com/v2/acts/rector_labs~markitdown-mcp-server/runs \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileUrl": "https://example.com/document.pdf"}'

Note: This server is primarily accessed as an MCP service exposed by Apify. The steps above focus on configuring an MCP client to talk to the Markitdown MCP server rather than running a local Python environment, since the server is designed to be cloud-hosted and MCP-enabled out of the box.

Tips and caveats:

• You can provide either fileUrl or fileBase64 in the input; providing both is not allowed.
• The service supports a wide range of formats (documents, images with OCR, HTML/XML, audio with transcription, archives, etc.).
• Expect typical conversion times under a few seconds for standard documents; larger or OCR-heavy files may take longer.
• If you encounter 401/403 errors, verify your Authorization header token (YOUR_APIFY_TOKEN) or API token and ensure it is correctly passed to the MCP client.
• The pricing model is pay-per-use (start, then per conversion). Monitor usage to estimate costs.
• In Claude Desktop or other MCP clients, you’ll typically add the markitdown server under mcpServers with command npx and the mcp-remote wrapper as shown in the Quick Start example.
• If your environment requires explicit header handling, you can adjust the --header option or environment variables to securely inject tokens at runtime.