What is markitdown-mcp AGENTS.md?

Project instructions for MarkItDown MCP, a document-conversion service that turns files such as PDFs, Word documents, spreadsheets, and presentations into readable Markdown text.

They are for converting documents, extracting their text, checking supported formats, and processing batches of files.

They show agents which conversion tool to use for individual files or whole directories and what information each call needs.

How trsdn/markitdown-mcp configures Codex and OpenCode

Reuse

Borrowing it

Nothing to install: this file belongs to trsdn/markitdown-mcp. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file

curl -O https://raw.githubusercontent.com/trsdn/markitdown-mcp/main/AGENTS.md

Clone the repo

git clone --depth 1 https://github.com/trsdn/markitdown-mcp

Made for: Codex, OpenCode.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/instructions/trsdn/markitdown-mcp/agents-md/github.svg)](https://agentmods.dev/instructions/trsdn/markitdown-mcp/agents-md)

Your own site

<a href="https://agentmods.dev/instructions/trsdn/markitdown-mcp/agents-md"><img src="https://agentmods.dev/badge/instructions/trsdn/markitdown-mcp/agents-md/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/instructions/trsdn/markitdown-mcp/agents-md"><img src="https://agentmods.dev/badge/instructions/trsdn/markitdown-mcp/agents-md.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 5,909 This file is loaded in full into every session.

When invoked 5,909 The same file — it is already loaded in full.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.05909	$0.05909
Opus 5.5	$0.02364	$0.02364
Sonnet 5.5	$0.01182	$0.01182
Haiku 4.5	$0.00591	$0.00591

Measured 1mo ago against content hash d9fac4a518b7, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

markitdown-mcp AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 1mo ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

AGENTS.md · 816 lines

How it starts

The opening of the file, as written. The whole thing — 816 lines — stays where its author put it; the contents beside it link to each section on GitHub.

AI Agents Integration Guide

This guide provides comprehensive information for AI agents and assistants on how to effectively use the MarkItDown MCP server for document conversion tasks.

Working in this repository

Read this section before changing anything here. The rest of this file is a usage guide for agents that call the server; this section is for agents that change its code.

What this repository is

An MCP server, published on PyPI as trsdn-markitdown-mcp, that converts documents to Markdown for MCP clients such as Claude Desktop. A change to a tool name or schema breaks every client that calls it.

Layout

Path	Purpose
`markitdown_mcp/`	The server package: `server.py` holds the MCP tools and the `main` entry point
`tests/`	Unit, integration, security, performance and compatibility tests
`schemas/`	Generated tool schemas. Never hand-edit; regenerate with `python scripts/generate-schemas.py`
`docs/`	Guides and API documentation. `docs/api/generated/` is produced by the documentation workflow
`.github/workflows/`	CI, release and maintenance automation. See `RELEASE.md` for the release pipeline

Validate before proposing a change

Set up with pip install -e ".[dev,test]", then run all of these; every one must pass:

ruff format --check . && ruff check . && mypy markitdown_mcp/
pytest tests/unit/

The CI job Unit Tests & Coverage runs the same tests, and CONTRIBUTING.md describes the pull request rules. Python 3.10 or later is required and is declared in pyproject.toml.

Do not do these

Do not rewrite history, force push, or delete branches.
Do not commit secrets, tokens, or personal data. Push protection is enabled; a blocked push means stop and tell the maintainer, not retry.
Do not create or move tags, publish to PyPI, or run the release workflow. A release is made from a tag by the pipeline described in RELEASE.md, and the maintainer starts it.
Do not change repository settings, branch protection, or the pypi environment. Those are maintainer actions.
Do not hand-edit schemas/*.json or anything under docs/api/generated/; change the source and regenerate.
Do not add a dependency without stating why in the pull request.
The server reads and writes files on the user's machine. Do not add a code path that reads outside the paths the caller supplies, and do not run convert_directory against a directory you were not asked to convert.

Read the full file on GitHub · 816 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

1mo ago Changed · +57 lines · +712 tokens per session d9fac4a518b7
2mo ago First seen · 759 lines · 5,197 tokens per session scan A 979d4ca116ac

Subscribe to this mod's changes

markitdown-mcp AGENTS.md is an instructions file published in the GitHub repository trsdn/markitdown-mcp (46 stars, last pushed today), licensed MIT. It adds 5,909 tokens to every session, about $0.0236 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Documents ai-tools claude-desktop document-conversion file-conversion markdown markitdown

markitdown-mcp AGENTS.md next to 6 instructions from other repositories
Mod	Type	Stars	Last push	Licence	Scan	Tokens	Works with
markitdown-mcp AGENTS.mdtrsdn/markitdown-mcp	Instructions file	46	today	MIT	A	5,909	Codex, OpenCode
vscode buildNext.instructions.mdmicrosoft/vscode	Instructions file	195k	today	MIT	A	9,719	GitHub Copilot
vscode oss-third-party-notices.instructions.mdmicrosoft/vscode	Instructions file	195k	today	MIT	A	5,516	GitHub Copilot
next.js AGENTS.mdvercel/next.js	Instructions file	143k	today	MIT	A	7,461	Codex, OpenCode
langchain AGENTS.mdlangchain-ai/langchain	Instructions file	149k	today	MIT	A	4,680	Codex, OpenCode
vscode copilot-instructions.mdmicrosoft/vscode	Instructions file	195k	today	MIT	A	3,093	GitHub Copilot
vscode model-prompts.instructions.mdmicrosoft/vscode	Instructions file	195k	today	MIT	A	2,022	GitHub Copilot

markitdown-mcp: Instructions file for Codex