Stop uploading raw PDFs to Claude, convert them first

A free Microsoft tool turns a PDF, Word file or slide deck into clean Markdown before it ever reaches Claude. Same information, a fraction of the tokens, and answers that come back sharper.

If your Claude usage runs out faster than it should, the PDFs are usually why. The fix is one line in a terminal: convert PDF to Markdown first, then upload the Markdown. Here is the workflow, including the parts that fail.

01 / The cost

Why a PDF costs you more tokens than it should

A PDF is not really a text file, it is a layout container. Column breaks, headers, footers, page numbers, embedded images and tables that only half survived the export are all sitting in there, and every one of them has to be read and interpreted before the actual point arrives. You pay for the reading.

Markdown is the opposite. It is plain text that keeps the parts carrying meaning, headings, lists, tables and links, and throws away everything that only describes appearance. That is precisely the part Claude needs.

Jargon, in one line

Markdown is plain text with a few small formatting marks: a # makes a heading, a - makes a bullet. Models were trained on an enormous amount of it, so they read it natively, and it happens to be unusually efficient with tokens. A token is roughly a chunk of a word, and it is the unit your usage limit is counted in.

02 / Setup

What you need before you start

• Python 3.10 or newer. Check yours with python --version. Windows users install it once from python.org, at no cost.
• MarkItDown itself. Free and open source, MIT licensed, built by Microsoft’s AutoGen team.
• A file to test on. Any PDF, Word doc, deck or spreadsheet you would normally drag straight into Claude.

03 / The workflow

How to convert PDF to Markdown before you upload

01

Install it once

Open Terminal on a Mac or Command Prompt on Windows and run pip install 'markitdown[all]'. The [all] part pulls in support for every file type it handles, or you can name only the ones you need with pip install 'markitdown[pdf, docx, pptx]'.

one time onlyIf you already use uv, skip the install entirely and run uvx 'markitdown[pdf]' report.pdf -o report.md, which fetches, runs and cleans up after itself.

markitdown on github →

02

Convert your first file

Move into the folder your file lives in, cd Downloads for example, then run markitdown report.pdf -o report.md. The first name is the file going in, -o names the Markdown file coming out, and the original is left untouched.

only the names changemarkitdown slides.pptx -o slides.md works the same way. Name the output like a note, since q3-board-deck.md beats output.md and the filename is the first thing Claude reads.

usage docs →

03

Open the .md and skim it

Never upload a conversion you have not glanced at. Open it in any text editor and check three things: the headings survived, the tables still read as tables, and there is no long stretch of blank where content should be.

quick testTry to select the text in the original PDF. If your cursor highlights words, MarkItDown can read it. If it highlights a whole rectangle like an image, the page is a scan.

what it drops →

04

Upload the Markdown and ask properly

Drag the .md file into Claude exactly as you would have dragged the PDF. Because the noise is gone, you can afford to spend what you saved on a much better question than “summarise this”.

why it mattersMost weak answers come from a vague question, not a weak model. Template below.

open claude →

05

Automate it away

Once converting by hand gets tedious, hand the job to Claude. A companion package, markitdown-mcp, wraps the converter as a connector Claude can call by itself, so you never open the terminal.

when to botherDo it by hand two or three times first. You want to see the difference in your own answers before you make the step invisible.

set up the connector →

Prompt template, fill in the blanks

This is [what the document is, for example a 20-page vendor contract], converted to Markdown. I need [what you actually want, for example every payment obligation and its deadline]. Quote the exact lines you are drawing from, and tell me plainly if something I have asked about is not in the document rather than guessing. Answer as [a short table / five bullets / a plain paragraph].

04 / Automation

Hand the conversion to Claude itself

In Claude Code it is a single line: claude mcp add markitdown -- uvx markitdown-mcp. Note the double dash, which separates the command from Claude’s own options.

In Claude Desktop, open Settings → Developer → Edit Config, add the block below, then quit the app completely and reopen it. Closing the window is not enough, because connectors only load on a fresh launch.

{ "mcpServers": { "markitdown": { "command": "uvx", "args": ["markitdown-mcp"] } } }

The server exposes exactly one tool, convert_to_markdown, which accepts a local file path or a web address. Point Claude at a document and ask your question in the same message.

A caveat worth reading

The server has no password on it and runs with your own file permissions, so it can reach anything you can reach. Keep it on your own machine, do not expose it over a network, and do not point it at files you do not trust.

05 / Limits

When MarkItDown will not help

Two limits look like the tool is broken when it is working as designed.

• Scanned pages come back empty. If your PDF is a photograph of a page rather than real selectable text, the standard PDF path has no OCR built in, meaning it cannot read letters out of a picture. Upload the original PDF instead and let Claude look at it directly. A markitdown-ocr plugin now covers this, but it routes images to a vision model, so it needs an API key and stops being free.
• Anything visual is dropped. Charts, images and page layout go by design. MarkItDown preserves meaning, not appearance, so a carefully art directed brochure arrives as plain paragraphs. If the layout is the message, this is the wrong tool.

06 / Range

It is not only PDFs

The same one line command handles Word, PowerPoint and Excel files, HTML pages, CSV, JSON and XML, EPub ebooks, images for metadata and text recognition, audio for metadata and speech transcription, YouTube links, and ZIP archives, which it opens and walks through file by file. Worth installing even if PDFs are what sent you here.

Watch out

Common mistakes when converting PDFs to Markdown in 2026

• Uploading a conversion you never opened. A silently half broken file wastes more of your time than the raw PDF would have.
• Assuming a fixed saving. The 70 percent figure that gets quoted is one file on one day. Convert two of your own and compare before you plan around it.
• Deleting the original. Keep the PDF. You will want it the day someone asks about a chart or a signature.
• Wiring up the connector on day one. Do it manually a few times first, or you will not know what changed when an answer gets worse.

Questions

FAQ

How many tokens will I actually save?

It depends entirely on the file. A dense, text heavy report can shrink a great deal, while a short and already clean PDF barely changes. Convert one of your own documents and compare the two uploads rather than relying on anyone’s headline number.

Do I need to know how to code?

No. You copy two lines into Terminal or Command Prompt and change the file names. If even that feels like too much, set up the connector once and Claude does the conversion for you from then on.

Will it work on a scanned PDF?

Not through the standard PDF path, which has no built in text recognition. You will get an empty or nearly empty Markdown file. Test by trying to select the text in the PDF: if you cannot highlight individual words, upload the original file to Claude instead.

What is the difference between MarkItDown and markitdown-mcp?

MarkItDown is the converter you run yourself from a terminal. markitdown-mcp is a separate package that wraps the same converter as a connector, so Claude can call it without you. Both are free, and both run locally on your own machine.