Guide

OpenClaw + MarkItDown: File-to-Markdown over Local MCP

Q: Is MarkItDown a remote service or a local install?

Local. MarkItDown installs into a Python virtual environment inside the instance and is registered as a stdio MCP server, so documents are converted in place rather than uploaded to an external parser.

Q: How is MarkItDown registered with OpenClaw?

As a stdio server under mcp.servers. The installer runs openclaw mcp add markitdown with the venv executable path and a 60 second connect timeout.

Q: What permissions does it run with?

MarkItDown runs with the bot’s existing file and network permissions because it is a local process inside the same instance.

Models read Markdown far better than they read a binary PDF. MarkItDown is Microsoft's converter for PDF, Office, HTML, CSV, images, audio, and archives — and on OpenClaw Launch it installs as a local MCP server, so documents never leave the instance.

Why a converter, not a bigger context window

Handing a model a raw PDF is usually the worst option available: layout noise, no reliable reading order, and page furniture competing with content. A converter collapses the document into Markdown with headings, lists, and tables preserved, which is both cheaper in tokens and easier for the model to reason about. MarkItDown covers the formats people actually attach — PDF, DOCX, XLSX, PPTX, HTML, CSV, images, audio, and ZIP archives — behind one interface.

1. Install from Dashboard Tools

Open Dashboard Tools, select a running OpenClaw or Hermes instance, and install MarkItDown. The installer builds an isolated Python virtual environment in the instance's tools/ directory, installs the pinned markitdown and markitdown-mcp versions, rewrites the entry point's interpreter line so the executable is self-contained, then registers it with the agent runtime.

2. What gets written to the config

On OpenClaw the installer registers a stdio MCP server through the CLI rather than hand-editing JSON, which keeps validation and the config watcher on your side:

openclaw mcp add markitdown \
  --command /home/node/.openclaw/tools/markitdown-mcp-<version>/bin/markitdown-mcp \
  --connect-timeout 60

That lands as a stdio entry under mcp.servers in openclaw.json. On Hermes the equivalent goes into mcp_servers in config.yaml with the same command and a 60 second connect timeout. A backup copy of the previous config is written before the first change, so an install is reversible.

3. Verify before you trust it

openclaw mcp list
openclaw mcp show markitdown
openclaw mcp probe markitdown

A probe opens a real MCP session and lists capabilities. That separates a transport or interpreter problem from a model or prompt problem — which matters here, because a venv whose interpreter line was not rewritten fails at spawn time, not at tool-call time.

One naming trap: openclaw mcp tools <name> is not the listing command it sounds like. It updates that server's include and exclude tool filters, so use probe and show to inspect and keep tools for when you actually want to narrow what the agent can call.

4. Give it a concrete file

The strongest prompt names the file and the shape you want back: "Convert the invoice in the workspace to Markdown and give me the line items as a table." Conversion is deterministic; the interesting work is what the agent does with the Markdown afterwards. Keep source documents in the workspace so later turns and the file manager can still see them.

Scope and safety

MarkItDown runs as a local process with the bot's file and network permissions — a URL source is a network fetch by the agent.
Large scanned PDFs are images. If the text is not embedded, you need OCR, not conversion — see PaddleOCR.
Converted output lands in the conversation unless you ask for it written to a file; be deliberate with confidential documents.
The install is pinned. Reinstall from the dashboard rather than upgrading the package in place, or the managed marker stops matching.

MarkItDown versus the PDF-specific tools

MarkItDown is the right default: one tool, many formats, no server to run. Reach for Stirling PDF when you need to manipulate the PDF itself — split, merge, redact, sign — rather than read it, and for PaddleOCR when the pages are scans with no text layer at all.

Frequently asked questions

Is MarkItDown a remote service or a local install?

Local. The dashboard creates a Python virtual environment inside the instance, installs pinned markitdown and markitdown-mcp releases, and registers the resulting executable as a stdio MCP server. No file ever leaves the instance for conversion.

How is MarkItDown registered with OpenClaw?

As a stdio entry under mcp.servers. The installer calls openclaw mcp add markitdown --command <path> --connect-timeout 60, which is the supported way to register a local command-based MCP server in current OpenClaw releases.

What permissions does it run with?

The bot's own. MarkItDown is a local process, so it can read whatever the agent can read and reach whatever the agent can reach. Treat a request to convert an arbitrary URL or path the same way you would treat any other file or network action by the agent.