Drop in a file or a web page, get agent-ready Markdown out — and let your AI read it directly, for a fraction of the tokens.
A fast, self-hostable platform that turns any document or web page into clean, LLM-ready Markdown — and goes past the conversion to deliver visible quality control, RAG-ready output, token economics, and native AI-agent (MCP) access.
Getting started · Documentation · Use it from any agent · Contributing · Issues
Built and maintained by AnHourTec.
If TokenItDown saves you tokens, consider starring the repo — it genuinely helps other people find it.
The conversion engine itself is commoditized. Our value is the workflow around it — the library, the repair loop, the RAG export, the agent integration, and the web-capture extension — packaged cleanly for both cloud users and self-hosters.
Two deployment targets from one codebase:
- Cloud — multi-tenant SaaS with managed processing, billing, and a hosted MCP endpoint.
- Self-hosted — a single
docker compose up, all processing local, optional local-LLM mode, no data egress.
- Convert anything to Markdown — powered by Microsoft MarkItDown: PDF, Word, PowerPoint, Excel, images (OCR + EXIF), audio (transcription), HTML, CSV/JSON/XML, ZIP (iterated), EPUB, and YouTube / web-page URLs.
- Per-format convert pages — a dedicated page per source type, each with drag-and-drop batch upload, a document-scan animation while converting, and a GitHub-style rendered result.
- Library — every converted document in a file viewer with a Preview / Raw toggle (rendered Markdown via
react-markdown+ GFM, or syntax-highlighted source via Shiki), plus copy, download, and delete. - Documents — every original uploaded file, previewed in place, with an Original / Markdown toggle. Originals are stored on a local volume; the converted Markdown lives in Postgres.
- Real-data dashboard — KPIs (documents, tokens saved, agent conversions, originals stored), a 30-day conversion-activity chart, recent conversions, source breakdown, and top token-savers.
- Use it from your AI coding agent (MCP) — a built-in Model Context Protocol server lets Claude Code, Cursor, VS Code Copilot, or Claude Desktop call TokenItDown automatically the moment you hand the agent a file or URL. Runs local (stdio) for converting your own files with no account, or hosted (HTTP) for remote agents with a per-user API key.
- Works with any agent, not just Claude — the Connect editor page offers per-editor install snippets and downloadable, instance-aware
AGENTS.md/CLAUDE.md/skills.mddrop-in files (viewable full-page) so Codex, Cursor, Gemini, Windsurf, Cline, Aider, or any MCP host knows to use TokenItDown. - Per-user API keys + full transparency — issue revocable API keys from the dashboard. Conversions an agent makes with a key run through the same pipeline as the dashboard (cleaned, token-counted, saved to your Library) and are attributed to that key, so the Connect page shows, per key, how many calls it made, tokens saved, and exactly what it converted.
- Auth — email/password with httpOnly cookie sessions (better-auth) stored in Postgres, CSRF via trusted origins, protected dashboard.
| Connect any AI agent (MCP) | Library |
|---|---|
 |
 |
| Per-user API keys, usage & drop-in files | Preview / raw, token savings |
 |
|
| Convert any format | Real-data dashboard |
TokenItDown ships a Model Context Protocol server so your agent calls it the moment you hand it a file or URL — no copy-pasting, and a fraction of the tokens.
# Claude Code — local (converts your own files, no account):
claude mcp add tokenitdown -- python -m app.mcp_server
# Hosted — create an API key on the dashboard's "Connect editor" page, then:
claude mcp add --transport http tokenitdown https://<host>:8001/mcp \
--header "Authorization: Bearer YOUR_TOKENITDOWN_API_KEY"Three tools become available to the model: convert_url_to_markdown, convert_file_to_markdown (local), and convert_document (hosted). In hosted mode each conversion is proxied through the web pipeline, so it's cleaned, token-counted, saved to your Library, and attributed to the key. See the AI agents docs for per-editor setup.
- Web — Next.js app (dashboard, auth, API routes). Conversions are proxied from
app/api/convert*to the processing service over an internal network, gated by a shared secret. The convert routes accept either a session (dashboard) or anAuthorization: Bearer tid_…API key (agents). - Processing service (
server/) — a Python FastAPI wrapper aroundmarkitdown[all]with/convert(uploads) and/convert-url(SSRF-guarded). Internal-only. - MCP server (
server/app/mcp_server.py) — themarkitdown-mcpcontainer. In hosted/HTTP mode it authenticates an agent's API key and proxies conversions back through the web pipeline, so agent activity is cleaned, tracked, and saved like any other conversion. - Postgres — users, sessions, converted documents (tagged with the API key that created them), and API keys (Drizzle ORM). Keys are stored as SHA-256 hashes; the full token is shown once.
- Redis — reserved for the job queue / session store.
Full details — every service, the request lifecycle, the MCP/agent flow, security boundaries, and the data model — are in the Architecture docs.
- Next.js 15 (App Router) + React 19, strict TypeScript with ts-reset
- Tailwind CSS v4 + Radix UI + CVA; react-markdown, Shiki, recharts, sonner
- better-auth + Drizzle ORM + PostgreSQL
- Processing: Python / FastAPI / MarkItDown / FastMCP
- Testing: Vitest, Playwright, pytest; T3 Env + OpenTelemetry
- Node.js
>=22and npm (the project's package manager) - Docker + Docker Compose (for Postgres/Redis and the full-stack deploy)
- Python
>=3.10(only if running the processing service outside Docker)
# 1. Install deps
npm install
# 2. Configure env
cp .env.example .env # then fill in secrets (BETTER_AUTH_SECRET, MARKITDOWN_SERVICE_TOKEN, DB creds…)
# 3. Bring up Postgres, Redis and the MarkItDown service
docker compose up -d postgres redis markitdown
# 4. Run the web app (auto-creates the DB + applies migrations)
npm run devOpen http://localhost:3000. Register, then convert from Convert in the sidebar; view results in Library and originals in Documents.
The self-hosted edition ships as a docker compose bundle — web + Postgres + Redis + the MarkItDown processing service + the MCP server + the docs site. On the host, copy .env.example → .env, set real secrets (including MARKITDOWN_SERVICE_TOKEN), then:
./deploy.shThis builds the images and brings the stack up; the web container waits for the processing service, ensures the database, and runs migrations on startup. Everything is reachable through one origin:
- App —
http://<host>:${WEB_PORT:-3030} - Docs —
http://<host>:${WEB_PORT:-3030}/docs(the web app proxies/docsto the docs container; there's also a Docs link in the sidebar) - MCP endpoint —
http://<host>:${MCP_PORT:-8001}/mcp
The docs are a Nextra site in docs/, served at /docs on the running app (e.g. http://<host>:3030/docs) — no separate port. To work on them locally alongside the app:
# terminal 1 — the app on :3000
npm run dev
# terminal 2 — the docs on :3040 (served under /docs via basePath)
cd docs && npm install && npm run dev -- -p 3040
# to preview the same-origin proxy, set DOCS_INTERNAL_URL in .env and restart the app:
# DOCS_INTERNAL_URL=http://localhost:3040
# then open http://localhost:3000/docsIt covers Getting Started, Self-Hosting, Configuration, Converting, the Library, RAG Export, the AI agents / MCP integration, Architecture, an API reference, the roadmap, and an FAQ.
Contributions are welcome! See CONTRIBUTING.md for how to set up the project, the conventions we follow, and how to open a good pull request — especially how to report agent / MCP compatibility issues (which agent, which transport, which install snippet). Check the open issues for things to work on.
Found a security vulnerability? Please report it privately rather than opening a public issue — see the Security section.
Conversion is powered by Microsoft MarkItDown. TokenItDown is the workflow, quality control, RAG export, and agent integration around it.
MIT © AnHourTec