Optimizing Token Costs in Document Processing with Microsoft MarkItDown

Every time you upload a PDF file to Claude, the actual cost is significantly higher than the word count in the document would suggest. The reason lies in how Claude processes PDFs, and there is already a free tool that solves this.

This guide explains where these costs come from, provides step-by-step installation instructions, daily commands, how to configure Claude to automatically convert files, along with cases where you should not use MarkItDown.

No programming knowledge is required. The entire process only involves copying and pasting a single line of command.

1. Explanation of Terms Used in the Documentation

This document contains several technical terms. Click on any unfamiliar term to expand its explanation, or skip it if you are already familiar.

2. Why Does Uploading PDFs to Claude Consume More Usage and Money?

When processing a PDF file, Claude does not just read the text. The actual process consists of three steps: The system converts each document page into an image, then extracts the text from that page and provides it alongside the image. In other words, the document is ingested as both text and images.[1]

There is a good reason for this approach: With images, Claude can read charts, diagrams, signatures, and complex layouts. The issue lies in the fact that users are billed for both parts, even when the document contains only text and the image component provides no additional information. For those who process client documents daily (contracts, reports, records, minutes), this is the primary reason usage runs out unexpectedly fast. The thicker the document, the higher the overhead cost incurred by images.

Also according to Anthropic’s documentation, a request containing a PDF is limited to 32 MB and a maximum of 600 pages (only 100 pages if you use a model with a context window under 1 million tokens). The documentation also warns that dense PDFs with small text, complex tables, and many figures can overflow the context window before reaching the page limit.[1]

In other words, staying under 600 pages does not automatically mean you are safe. Converting to markdown is the simplest way to expand both of these limits.

3. What is MarkItDown and which formats does it support?

MarkItDown is a free, open-source tool released by Microsoft. Its core functionality can be summed up in one sentence: It takes a document file as input and outputs a clean markdown file for AI to read.[3]

The project’s repository currently has over 180,000 stars on GitHub, placing it among the most popular projects in the field of document processing for AI.[3]

Once the document is in markdown format, there are no more pages to convert into images. Claude receives only pure text, so the cost is calculated strictly on the actual content, with no extra charges incurred from snapshots of that very same content.

According to the repository’s documentation, MarkItDown can handle a wide variety of popular formats:

• Office documents: PDF, Word (.docx), Excel (.xlsx, .xls), PowerPoint (.pptx).
• Data and source code: HTML, CSV, JSON, XML, ZIP archives, EPUB e-books.
• Multimedia: Image files (EXIF metadata extraction and OCR text recognition), audio files (EXIF reading and speech transcription), and even YouTube video links.

4. 5-Minute Installation and Usage Guide

This section is for those who have never opened the Terminal. Follow the four steps below in order to install and convert your first file.

Step 1: Check Python on Your Computer

Open Terminal (Mac: Press Cmd + Space, type “terminal”, press Enter) or Command Prompt (Windows: Press the Windows key, type “cmd”, press Enter). Paste the check command below and press Enter:

python3 --version

If the result displays a line like Python 3.12.x, Python is already installed on your computer, and you can proceed to Step 2. If it displays a command not found message, visit python.org/downloads to download and install the latest version. On Windows, make sure to check the box “Add Python to PATH” on the first installation screen. On Windows, if the python3 command does not work, try python --version.

Step 2: Install MarkItDown

Still in that Terminal window, copy and paste the command below and press Enter. The process takes about a minute and displays several lines of messages:

pip install 'markitdown[all]'

Note for Windows PowerShell: Single quotes do not work; use the command with double quotes instead:

pip install "markitdown[all]"

The [all] part means installing all optional dependencies to read various file formats. If you only need specific formats, you can install them individually to save space, for example, pip install 'markitdown[pdf, docx, pptx]'.

brew install pipx && pipx install 'markitdown[all]'

Step 3: Convert your first file

To avoid typing long file paths: Type markitdown followed by a space, then drag and drop the file you want to convert directly from Finder or File Explorer into the Terminal window. The path will be filled in automatically. Next, type -o followed by the output file name.

markitdown tailieu.pdf -o tailieu.md

This command means: Take the file tailieu.pdf and write the output to tailieu.md. The -o flag stands for output, specifying where to save the result.

If there are no error messages, the conversion was successful. The tailieu.md file will be located in the current directory and can be opened with Notepad or TextEdit to review.

This syntax is not limited to PDFs. Simply change the file extension to use it with Word, Excel, PowerPoint, CSV, HTML, and other formats from the list above, keeping the -o flag unchanged.

markitdown baocao.xlsx -o baocao.md
markitdown ketoan.docx -o ketoan.md

Step 4: Check the output before using

This step is often overlooked, but it is essential. Open the newly created .md file and quickly check the following three points:

• Whether the file contains text: If the file is nearly empty, the original PDF is a scanned document. How to handle this is covered in Part 8.
• Whether tables retain their structure: Markdown tables are displayed as rows separated by vertical bars (pipes). If the data is merged into a single block, the original document has a complex layout and an alternative approach should be considered.
• Whether Vietnamese diacritics are intact: If the text is missing tone marks or displaying strange characters, the root cause lies in the font of the original PDF, not an issue with MarkItDown.

How to verify the savings yourself: Pick a multi-page document and test it twice across two separate chats: once by dragging the PDF file in, and once by pasting the markdown content, using the exact same prompt. The thicker the document, the more noticeable the difference. For API users, Anthropic provides a built-in token counting tool to measure accurately before sending.[4]

5. Commands you will use daily

In practice, you only need to remember about five commands, all of which are available in the repository’s official documentation.[3]

Writing the Output to a File

markitdown baocao.pdf -o baocao.md
markitdown baocao.pdf > baocao.md

The second line uses the greater-than sign to write the output to a file. Both methods produce the same result.

Quick Preview Without Creating a File

Omit the -o flag to print the output directly to the terminal screen. This is useful when you just need to quickly verify if the file is readable.

markitdown baocao.pdf

Convert an Entire Folder in One Go

This command is useful when you need to batch process documents. It iterates through every PDF file in the current directory and creates a corresponding markdown file.

for f in *.pdf; do markitdown "$f" -o "${f%.pdf}.md"; done

If you prefer not to type the command above, Part 7 provides ready-to-use scripts for both Mac and Windows—simply download and run.

Enable OCR for Scanned PDFs

MarkItDown can utilize Microsoft’s Azure Document Intelligence service to read scanned PDFs. This service requires an Azure account and incurs separate fees, so this section is intended for those already using Azure.

markitdown banscan.pdf -o banscan.md -d -e "<endpoint-cua-ban>"

View available plugins

MarkItDown allows you to install plugins, which are community-developed extensions designed to support additional, less common formats.

markitdown --list-plugins
markitdown --use-plugins tailieu.pdf -o tailieu.md

For developers: MarkItDown can also be used in Python with just three lines of code, making it ideal for embedding into automated workflows: from markitdown import MarkItDown, followed by md = MarkItDown(), and then print(md.convert("baocao.xlsx").markdown).[3]

6. Installing the MCP Server: Let Claude Automatically Convert Files

This section is for daily Claude Desktop users. Microsoft has released an official MCP server for MarkItDown. Once installed, Claude will automatically convert files to Markdown whenever needed, and users will no longer need to open the Terminal.[5]

Installing the MCP Server for Claude Desktop (One-time Setup)

1. Open Terminal, paste pip install markitdown-mcp, and press Enter.
2. Open Claude Desktop, go to Settings, select the Developer tab, and click Edit Config. A file named claude_desktop_config.json will open.
3. Paste the configuration snippet below into that file and save it (Cmd + S on Mac, Ctrl + S on Windows).
4. Fully quit Claude Desktop and reopen it. This step is mandatory; without restarting, the configuration will not take effect.
5. Try sending Claude a prompt like “Convert this file to markdown” along with the file path. If Claude asks for permission to use the tool, the installation was successful.

Configuration file locations if you want to open it directly: On Mac, it is located at ~/Library/Application Support/Claude/, and on Windows, it is at %APPDATA%Claude.

{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp"
    }
  }
}

If the configuration file already contains content: Do not delete the existing content and overwrite it. If the file already has an "mcpServers" section with other tools, simply add the "markitdown" block inside it, making sure to separate blocks with commas. A missing or extra comma will prevent Claude from reading the file, and usually without a clear error message.

Functions of the MCP Server

The MCP server provides Claude with a single tool named convert_to_markdown, which accepts a file address and returns markdown. The address can be http:, https:, file:, or data:.[5] As a result, Claude can convert an entire webpage or a local file on your machine, not just PDFs.

Usage Note: After installing the MCP server, you need to change your workflow habits. Instead of dragging and dropping the PDF file into the chat box (which causes Claude to convert each page into an image), send the file path and ask Claude to convert it first. Dragging the file directly will bring you right back to the very issue you want to avoid.

7. Ready-to-use scripts and prompts

The five items below can be copied directly from this page, no typing required. Just click Copy in the top-right corner of each box and paste them into the designated places according to the notes.

MarkItDown Toolkit for Beginners

4 Mac and Windows files — No coding required

Includes an MCP configuration file to paste directly into Claude Desktop, two folder batch conversion scripts (one for Mac and Linux, one for Windows), and a short guide file. The script automatically creates a markdown directory inside the source folder and outputs the results there, so your original files remain unchanged.

{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp"
    }
  }
}

#!/usr/bin/env bash
# ------------------------------------------------------------
# Convert entire folder to Markdown using MarkItDown
# For Mac and Linux. Requirement: markitdown pre-installed
#   pip install 'markitdown[all]'
#
# Terminal usage:
#   bash convert-entire-folder.sh "/path/to/folder"
# Leave path empty to run the script in the current directory.
# Results are saved in a subfolder named "markdown".
# Original files remain unchanged.
# ------------------------------------------------------------
set -uo pipefail

SRC="${1:-.}"

if [ ! -d "$SRC" ]; then
  echo "Directory not found: $SRC"
  exit 1
fi

OUT="$SRC/markdown"
mkdir -p "$OUT"

shopt -s nullglob nocaseglob

ok=0
fail=0

for f in "$SRC"/*.pdf "$SRC"/*.docx "$SRC"/*.pptx "$SRC"/*.xlsx "$SRC"/*.csv "$SRC"/*.html "$SRC"/*.epub; do
  base="$(basename "$f")"
  name="${base%.*}"
  echo "Converting: $base"
  if markitdown "$f" -o "$OUT/$name.md" 2>/dev/null; then
    ok=$((ok + 1))
  else
    echo "  Skipped, unreadable: $base"
    fail=$((fail + 1))
  fi
done

echo ""
echo "Done. Succeeded: $ok file(s). Skipped: $fail file(s)."
echo "Results located in: $OUT"
echo "Note: If an output file is nearly empty, the original is likely a scan requiring OCR."

@echo off
REM ------------------------------------------------------------
REM Convert entire folder to Markdown using MarkItDown
REM For Windows. Requirement: markitdown already installed
REM   pip install "markitdown[all]"
REM
REM Easiest usage: Drag and drop the folder to convert onto this .bat file.
REM Or run in Command Prompt:
REM   convert-entire-folder.bat "D:Tai lieuHop dong"
REM
REM Output will be saved in a subfolder named "markdown".
REM Original files remain unchanged.
REM ------------------------------------------------------------
setlocal enabledelayedexpansion

set "SRC=%~1"
if "%SRC%"=="" set "SRC=%CD%"

if not exist "%SRC%" (
  echo Folder not found: %SRC%
  pause
  exit /b 1
)

set "OUT=%SRC%markdown"
if not exist "%OUT%" mkdir "%OUT%"

set /a OK=0
set /a FAIL=0

for %%E in (pdf docx pptx xlsx csv html epub) do (
  for %%F in ("%SRC%*.%%E") do (
    echo Converting: %%~nxF
    markitdown "%%~fF" -o "%OUT%%%~nF.md" 2>nul
    if errorlevel 1 (
      echo   Skipped, unreadable: %%~nxF
      set /a FAIL+=1
    ) else (
      set /a OK+=1
    )
  )
)

echo.
echo Done. Success: !OK! files. Skipped: !FAIL! files.
echo Output saved in: %OUT%
echo Note: If any output file is nearly empty, the original is a scanned document and requires OCR.
pause

# MarkItDown Starter Toolkit for Beginners

Documentation accompanying the tutorial from the DevPixel VN channel.
The files in this package were prepared by the channel, not the original Microsoft files.
Original MarkItDown repository: https://github.com/microsoft/markitdown

## What's in the package


1. `claude-desktop/claude_desktop_config.json`
   Configuration to connect MarkItDown to Claude Desktop via MCP.
2. `scripts/chuyen-doi-ca-thu-muc.sh`
   Script to convert an entire directory to markdown, for Mac and Linux.
3. `scripts/chuyen-doi-ca-thu-muc.bat`
   Similar script, for Windows.
4. `prompt/doc-tai-lieu-markdown.txt`
   Prompt to ask Claude to analyze documents after conversion.

## Step 1: Install MarkItDown


Open Terminal (Mac) or Command Prompt (Windows), run:

    pip install 'markitdown[all]'

On Windows PowerShell, use double quotes:

    pip install "markitdown[all]"

If you encounter an externally-managed-environment error on Mac, install via pipx:

    brew install pipx
    pipx install 'markitdown[all]'

## Step 2: Test converting a file


    markitdown tailieu.pdf -o tailieu.md

Open the newly created .md file to check. If it is nearly empty, the source file is a scanned document.

## Step 3: Convert an entire directory


Mac and Linux:

    bash scripts/chuyen-doi-ca-thu-muc.sh "/path/to/directory"

Windows: Drag and drop the folder you want to convert onto the
`scripts/chuyen-doi-ca-thu-muc.bat` file.

The results will be located in a subfolder named `markdown`. Original files remain untouched.

## Step 4: Connect to Claude Desktop (optional)


    pip install markitdown-mcp

Open Claude Desktop, go to Settings, Developer tab, click Edit Config,
paste the contents of `claude-desktop/claude_desktop_config.json`,
save, then completely quit Claude Desktop and reopen it.

If your configuration file already contains an mcpServers section with other tools,
only add the markitdown block inside it and remember the separating comma.

## Important Notes


- MarkItDown cannot automatically read scanned PDFs. You need to enable OCR via Azure
  Document Intelligence, or use another method for those files.
- For documents where information is contained in charts, diagrams, or drawings, the
  markdown version will lose that content. In such cases, keep the original files.
- Always open and quickly review the .md file before trusting its content.

Prompt for Reading Converted Documents

1 Ready-to-use Prompt

Prompt designed for long documents after conversion. The prompt content forces Claude to cite exact locations within the document and explicitly state when information cannot be found, rather than speculating.

You are a document reading assistant. Below is a document that has been
converted to markdown, meaning the text is accurate but images, charts,
and diagrams from the original version are no longer present.

Follow these steps in exact order:

1. Summarize the document in a maximum of 8 bullet points. One key idea
   per line, written in simple Vietnamese, avoiding technical jargon
   unless necessary.

2. List all important numbers, dates, proper names, and key clauses.
   For each item, include the section heading where it appears in the
   document so I can look it up.

3. Point out up to 5 points of attention: Any areas that could pose a risk,
   contain contradictions, or are phrased ambiguously.

4. Identify any places where the document refers to images, charts,
   blueprints, or appendices whose contents are not in the text. These
   are the spots where I will need to reopen the original file to view.

Mandatory rules:

- Only use information contained within the document. Do not speculate,
  and do not add external knowledge.
- If I ask about something the document does not mention, state directly:
  "The document does not mention this."
- When quoting a sentence, quote it verbatim and place it in quotation marks.
- If you notice truncated content or formatting errors, inform me
  immediately at the beginning of your response.

The document starts here:

Regarding the origin of the files: The script and prompt files above were compiled by the DevPixel VN channel and are not original Microsoft files. MarkItDown itself is installed via the pip command, which fetches the official release directly. The original source code is always available in the repository on GitHub, fully viewable by anyone.

8. When MarkItDown is not suitable

This part is rarely mentioned, but it is very important. Converting to markdown is a trade-off: discarding visual elements to save tokens. In some cases, those visual elements are the very information you need.

Three cases where you should keep the original file

• The PDF is a scanned document: Meaning a photograph or scan of a physical page. MarkItDown has no text to extract, so the resulting markdown file is virtually empty. Conversely, Claude reads scanned documents quite well precisely because it can process images. For this group of files, you need to add OCR or keep the original as is.
• Information is contained in charts, diagrams, or illustrations: Financial reports with graphs, technical drawings, process flowcharts. The text only contains part of the information, the rest is in the images, and converting to markdown will cause the visual part to be lost.
• The layout determines the meaning: Multi-cell forms, invoices, nested tables, two-column documents. When the layout is flattened into text, the reading order can get shifted and data can easily be mapped to the wrong place.

Safety rule: For critical documents (contracts, legal records, reports with numerical data), always open the markdown file to check it before feeding it to AI. A minute of review is better than an incorrect answer of unknown origin. No matter how good the conversion quality is, critical decisions still require cross-referencing with the original.

A Compromise Solution

You don’t necessarily have to choose between the two. For documents that contain both heavy text and images, you can do the following:

1. Convert to markdown so Claude can read the entire text at a low cost.
2. Ask questions and work primarily on the markdown version.
3. When you need a specific chart or a particular page, crop and attach only that single page. The cost will then only be charged for one image instead of twenty.

9. Habits that help save usage in the long run

• Convert when documents are a few pages or more: For one- or two-page files, the difference is negligible. From around five pages up, the costs incurred from images become noticeable. Contracts, reports, and long dossiers yield the highest savings.
• Make conversion a standard step: If your daily work involves processing client documents, avoid converting files one by one as needed. Run a script to batch-convert the entire folder once at the start of the day.
• Keep the markdown files: These files are lightweight, searchable via your computer’s native search tools, and reusable later without needing to be converted again.
• Trim unnecessary sections: Markdown files are plain text, so deleting a few irrelevant chapters takes just a few seconds—something you cannot do easily with PDFs. This is an overlooked way to save tokens.
• Break down excessively long documents: Anthropic’s documentation also recommends splitting large documents into parts instead of loading everything at once.[1] With markdown, splitting by chapter is very straightforward.
• Use an MCP server if you frequently work in Claude Desktop: Set it up once for long-term use; just remember to send file paths instead of dragging and dropping files into the chat window.

10. Frequently Asked Questions (FAQ)

11. Quick Summary

Key Takeaway: Dragging a PDF directly into Claude means paying extra image costs for every single page—something few people realize. With just a single conversion step, a 60,000-token document can be reduced to a fraction of that size, using the exact same content and achieving the same response quality.

Read next: 8 Web Design Skills for Claude Code