Markitdown

You run a Markitdown MCP Server to convert diverse file formats into Markdown through a request-driven, pay-per-use MCP gateway. This setup lets clients send content through an MCP client, have it converted by Markitdown, and receive clean Markdown outputs on demand, with automatic session handling and standby availability for instant readiness.

How to use

Set up the MCP server in standby or deploy it to your MCP-enabled environment. Expose an HTTP endpoint that MCP clients can reach, and, if you run locally, you can access the MCP gateway at a local address such as http://localhost:5001/mcp. Connect your MCP client to either a remote MCP URL or the local standby endpoint, and configure your client to send convert requests to the markitdown MCP server.

How to install

Prerequisites: Python 3.10 or higher, Poetry for dependency management. Docker is optional if you want containerized development.

1. Clone the project locally.

git clone https://github.com/Yash-Kavaiya/Markitdown-MCP-actor.git
cd Markitdown-MCP-actor

2. Install dependencies with Poetry.

poetry install

3. Run the Actor locally in standby mode to expose the MCP endpoint.

# Start in standby mode for immediate MCP availability
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. When you deploy in Apify or another environment, you’ll receive a remote URL for the MCP endpoint that you can use in your clients.

Additional content

Environment variable you can tune is SESSION_TIMEOUT_SECS, which sets how long a session remains active before automatic cleanup. The default is 300 seconds (5 minutes).

Tool usage is billed through a pay-per-event model. The core tool exposed is convert_to_markdown, which converts various file formats to Markdown. You can configure your MCP client to call this tool and pass the file URI you want to convert. Pricing and session management help you understand costs and keep resources under control.

Deployment options include running the Actor in standby within Apify for near-instant availability or deploying to your own MCP-enabled environment with a direct HTTP endpoint. When using HTTP, point MCP clients to the /mcp path of your remote or local endpoint and supply any required authorization headers as configured.

Available tools

convert_to_markdown

Converts various file formats to Markdown by sending a request to the Markitdown MCP server and receiving Markdown output.