Markitdown MCP Server Actor
An Apify Actor that provides a Model Context Protocol (MCP) server for Markitdown, Microsoft's lightweight Python utility for converting various file formats to Markdown.
Overview
This Actor wraps the Markitdown MCP server as an Apify Actor, making it easy to deploy and use as a pay-per-event service. Markitdown converts various file formats to Markdown, making them suitable for use with Large Language Models (LLMs) and text analysis pipelines.
Supported File Formats
- Documents: PDF, PowerPoint, Word, Excel
- Media: Images (with EXIF metadata and OCR), Audio (with transcription)
- Web Content: HTML, YouTube URLs
- Data Formats: CSV, JSON, XML
- Archives: ZIP files, EPubs
Features
- MCP Protocol: Implements the Model Context Protocol for seamless integration with MCP clients
- Streamable HTTP Transport: Uses modern Streamable HTTP transport for efficient communication
- Pay-per-Event: Charges only for actual tool usage via Apify's pay-per-event system
- Session Management: Automatic session timeout and cleanup after inactivity
- Standby Mode: Runs in Apify's standby mode for instant availability
How It Works
The Actor runs a proxy server that:
- Connects to the Markitdown MCP server via STDIO transport
- Exposes a Streamable HTTP endpoint at
/mcp - Forwards MCP requests/responses between clients and the Markitdown server
- Charges for tool usage via Apify's pay-per-event system
Available Tools
convert_to_markdown
Converts various file formats to Markdown.
Parameters:
uri(string): The URI of the file to convert. Supports:http://andhttps://- Remote filesfile://- Local filesdata:- Data URIs
Example:
{
"uri": "https://example.com/document.pdf"
}
Usage
1. Deploy the Actor
Deploy this Actor to Apify or run it locally in standby mode.
2. Configure Your MCP Client
Add the following configuration to your MCP client (e.g., VS Code, Claude Desktop):
{
"mcpServers": {
"markitdown-mcp-server": {
"type": "http",
"url": "https://YOUR_ACTOR_URL/mcp",
"headers": {
"Authorization": "Bearer YOUR_APIFY_TOKEN"
}
}
}
}
3. Use the Tool
Once configured, you can use the convert_to_markdown tool in your MCP client:
Convert this PDF to markdown: https://example.com/document.pdf
Environment Variables
SESSION_TIMEOUT_SECS(default: 300): Session timeout in seconds before terminating idle sessions
Pricing
The Actor uses Apify's pay-per-event system with the following rates (configurable in .actor/pay_per_event.json):
- CONVERT_TO_MARKDOWN: $0.01 per conversion
- TOOL_LIST: $0.0001 per listing
- RESOURCE_LIST: $0.0001 per listing
- RESOURCE_READ: $0.001 per read
- PROMPT_LIST: $0.0001 per listing
- PROMPT_GET: $0.001 per get
Local Development
Prerequisites
- Python 3.10 or higher
- Poetry for dependency management
- Docker (optional, for containerized development)
Installation
- Clone the repository:
git clone https://github.com/Yash-Kavaiya/Markitdown-MCP-actor.git
cd Markitdown-MCP-actor
- Install dependencies:
poetry install
- Run the Actor locally:
poetry run python -m src
Running in Standby Mode
To run the Actor in standby mode (required for MCP server operation):
export APIFY_META_ORIGIN=STANDBY
export ACTOR_STANDBY_URL=http://localhost:5001
poetry run python -m src
The MCP endpoint will be available at: http://localhost:5001/mcp
Project Structure
Markitdown-MCP-actor/
├── .actor/ # Apify Actor configuration
│ ├── actor.json # Actor metadata and settings
│ ├── pay_per_event.json # Pricing configuration
│ ├── Dockerfile # Docker image definition
│ └── .actorignore # Files to exclude from build
├── src/ # Source code
│ ├── __init__.py # Package initialization
│ ├── __main__.py # Main entry point
│ ├── const.py # Constants and configuration
│ ├── models.py # Data models
│ ├── server.py # ProxyServer implementation
│ ├── mcp_gateway.py # MCP gateway logic
│ └── event_store.py # Event store for session management
├── pyproject.toml # Python dependencies and settings
├── .gitignore # Git ignore rules
└── README.md # This file
Customization
Charging Strategy
You can customize the charging strategy by editing .actor/pay_per_event.json. The default configuration charges:
- $0.01 per conversion (main operation)
- Minimal charges for metadata operations (listing tools, resources, prompts)
Session Timeout
Adjust the SESSION_TIMEOUT_SECS environment variable to control how long sessions remain active during inactivity. The default is 300 seconds (5 minutes).
Tool Whitelist
The Actor uses a tool whitelist defined in src/const.py:
TOOL_WHITELIST = {
'convert_to_markdown': ('CONVERT_TO_MARKDOWN', 1),
}
You can add more tools if the underlying Markitdown MCP server exposes them.
Architecture
The Actor implements a proxy architecture:
MCP Client (VS Code, Claude, etc.)
↓ (Streamable HTTP)
Proxy Server (This Actor)
↓ (STDIO)
Markitdown MCP Server
↓
Markitdown Library
Key components:
- ProxyServer: Manages HTTP server and session lifecycle
- MCP Gateway: Proxies MCP requests and handles charging
- Event Store: Maintains session history for resumability
- Session Manager: Handles Streamable HTTP transport
Related Links
License
Apache-2.0
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Support
For issues and questions:
- Open an issue on GitHub
- Contact via Apify Console
Acknowledgments
- Microsoft Markitdown - The underlying conversion tool
- Apify - Actor platform and infrastructure
- MCP Proxy - Inspiration for the proxy implementation