Skip to content

@tlelabs/md-mcp is an MCP server that lets an AI agent convert local PDF, DOCX, PPTX, XLSX and HTML files, web pages and PDF links to Markdown. It runs on your machine over stdio, reads the file from disk and sends it to POST /v1/convert with your API key; web pages and PDF links go to POST /v1/fetch and POST /v1/fetch-pdf.

Create an API key under API keys (see Authentication), then add the server to your client with the key in MD_API_KEY. Node.js 20 or newer is required.

Each command below installs the server for every project (user scope). Replace mdw_live_... with your key; the dashboard’s key dialog shows them with the key filled in.

Claude Code (~/.claude.json)

Terminal window
claude mcp add -s user md -e MD_API_KEY=mdw_live_... -- npx -y @tlelabs/md-mcp

Codex (~/.codex/config.toml)

Terminal window
codex mcp add md --env MD_API_KEY=mdw_live_... -- npx -y @tlelabs/md-mcp

Antigravity (~/.gemini/config/mcp_config.json; flags go before the name)

Terminal window
agy mcp add --env MD_API_KEY=mdw_live_... md -- npx -y @tlelabs/md-mcp

Devin (~/.config/devin/mcp_config.json; without -s user the server is saved in the project’s .devin/)

Terminal window
devin mcp add -s user md --env MD_API_KEY=mdw_live_... -- npx -y @tlelabs/md-mcp

Cursor (~/.cursor/mcp.json), Claude Desktop and other clients using mcpServers JSON. In Cursor, the dashboard’s Add to Cursor link writes the same entry after you confirm it.

{
"mcpServers": {
"md": {
"command": "npx",
"args": ["-y", "@tlelabs/md-mcp"],
"env": { "MD_API_KEY": "mdw_live_..." }
}
}
}

To raise the Codex tool timeout, add one line to the table codex mcp add wrote in ~/.codex/config.toml:

[mcp_servers.md]
# ... command and args written by codex mcp add ...
tool_timeout_sec = 600

Long PDFs that need OCR can take a few minutes. If your client stops waiting before the conversion ends, raise its tool timeout (Codex tool_timeout_sec, Claude Code MCP_TOOL_TIMEOUT in milliseconds).

Argument Description
path File to convert. Relative paths resolve against the server’s working directory
output_path Optional. Write the Markdown to this file instead of returning it; use it for long documents
overwrite Optional. Replace output_path if it exists (default false: an existing file is never replaced)
ocr, ocr_model, preserve_images Optional. Same as Convert a file

The result holds the Markdown (or the path it was saved to) and a summary: format, pages, OCR pages, credits charged and remaining, and warnings.

A file the API refuses as too large is split into parts on your machine. This covers a file over 50 MB, a PDF over 500 pages or one that needs more OCR than one request allows, a PPTX over 200 slides, an XLSX over 50 sheets, and a PPTX, XLSX, DOCX or HTML file over the XML limits of Formats and pricing. Each part is converted and the Markdown is joined in source order; each part is at most 50 MB. The summary says the file was split into parts and names each part (pages 1–500, slides 201–260, sheet "Data" rows 1–30000…).

The output can lose some quality where parts meet:

  • text spanning two parts may be split, so a paragraph or a table can break at the join;
  • a PDF part keeps its pages but loses the outline (bookmarks) and page labels;
  • an XLSX run of rows loses merged cells and hyperlinks;
  • names that point across parts are dropped (defined names, the active sheet).

A part that cannot be converted is listed in the summary as Not converted, and the other parts are still returned. If your credits run out midway, the parts already converted are returned and the summary says where it stopped.

Renders a web page and converts it, like Convert a web page.

Argument Description
url Public http/https URL of the page
output_path, overwrite Optional. As for convert_file
preserve_images Optional. Same as Convert a web page

Downloads a PDF from a link and converts it, like Convert a PDF from a link. A PDF the API refuses as too large (over 50 MB or 500 pages) is downloaded by the MCP server and split into parts like a local file. The server downloads it only from a public address; an address on your network is refused, after every redirect and every DNS lookup. The parts are charged like convert_file, with no download fee.

Argument Description
url Public http/https URL of the PDF
output_path, overwrite Optional. As for convert_file
ocr, ocr_model, preserve_images Optional. Same as Convert a file

The result of both tools holds the Markdown (or the path it was saved to) and a summary with the final URL, pages and credits.

Every call is a new conversion and is charged like POST /v1/convert: 1 credit per page, 15 credits per OCR page with ocr_model=auto (pricing). fetch_url costs 5 credits per fetch, whatever the length of the page; convert_pdf_url costs the PDF price plus 5 credits. Calling again with the same file or URL is charged again. A split file is charged for the pages of every part. For PDF and PPTX that is the same total as the whole file. DOCX, XLSX and HTML count a page per 3,000 characters in each part, so each part may add one page from rounding.

The server retries a request on its own only in these cases:

  • a part the API refused as too large is split in half and sent again; a refused request is not charged;
  • a rate-limited part is sent again after the wait the API asks for;
  • a part whose response was lost (a dropped connection, or a server error without the API’s answer) is sent again alone, up to 2 times. The lost response may already have been charged, so such a part may be charged twice. The summary names each part that was sent again; check Usage.

Checks that fail locally (missing file, a file over 50 MB that cannot be split, output_path already exists) run before upload and cost nothing. If the connection drops, the result says the conversion may have been charged: check Usage before converting again.

Variable Required Default
MD_API_KEY yes —
MD_API_BASE no https://api.md.tlelabs.com