MCP server
@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.
Set up
Section titled “Set up”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)
claude mcp add -s user md -e MD_API_KEY=mdw_live_... -- npx -y @tlelabs/md-mcpCodex (~/.codex/config.toml)
codex mcp add md --env MD_API_KEY=mdw_live_... -- npx -y @tlelabs/md-mcpAntigravity (~/.gemini/config/mcp_config.json; flags go before the name)
agy mcp add --env MD_API_KEY=mdw_live_... md -- npx -y @tlelabs/md-mcpDevin (~/.config/devin/mcp_config.json; without -s user the server is saved in the project’s .devin/)
devin mcp add -s user md --env MD_API_KEY=mdw_live_... -- npx -y @tlelabs/md-mcpCursor (~/.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 = 600Long 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).
The convert_file tool
Section titled “The convert_file tool”| 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.
Large files
Section titled “Large files”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.
The fetch_url tool
Section titled “The fetch_url tool”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 |
The convert_pdf_url tool
Section titled “The convert_pdf_url tool”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.
Billing
Section titled “Billing”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.
Environment
Section titled “Environment”| Variable | Required | Default |
|---|---|---|
MD_API_KEY |
yes | — |
MD_API_BASE |
no | https://api.md.tlelabs.com |