parse-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@parse-mcp parse the uploaded file to markdown"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
parse-mcp
One MCP, many parsers. Default markitdown (free, fast, MIT). Escalate to Docling (table-heavy, scanned PDFs) or LlamaParse (cloud, BYOK) when markitdown's quality isn't enough. Plus an interpret tool that pipes parsed markdown into Claude for "summarize / extract X" so you stop juggling parsers and anthropic skills.
Install
Open Claude Code, paste:
/plugin marketplace add adelaidasofia/parse-mcp
/plugin install parse-mcp@parse-mcpManual install (pre-plugin-marketplace). See SETUP.md for full details.
pip3 install --break-system-packages -r requirements.txt
pip3 install --break-system-packages 'markitdown[pdf,docx,pptx,xlsx]'Then register the server in your client's .mcp.json:
{
"mcpServers": {
"parse": {
"command": "python3",
"args": ["/absolute/path/to/parse-mcp/server.py"]
}
}
}Related MCP server: Document Parser MCP
Tools
Tool | What it does |
| File path or http(s) URL to markdown. Router picks backend, falls back on empty/error. Returns markdown plus a chain of every backend attempted. |
| Shortcut for HTTP(S) inputs. Same return shape as |
| Parse + write the result as a markdown note in the vault. Default folder: |
| Parse first, then ask Claude over the parsed markdown. Cache hits reuse parsed text for free input tokens. |
| Which backends are installed + which are missing. Diagnostic. |
| Run every available backend on the same input. Compare latency + output side by side. |
| Chunk parsed markdown into retrieval-ready pieces using a doc-type-aware chunker. |
| Diagnostic. Run structural heuristics over markdown and return the doc_type that |
Backends (priority order)
markitdown (default, MIT, base install). PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, XML, EPub, ZIP. Fast, deterministic.
docling (optional,
pip install docling). Best for complex tables (97.9% on benchmark) + scanned PDFs. Downloads model weights on first run.llamaparse (optional, BYOK,
pip install llama-cloud-services+LLAMA_CLOUD_API_KEY). Cloud, cleanest output on visually-complex PDFs.
Routing strategy
parse(source)with nobackendarg: router picks based on file format, falls back if backend errors or returns empty.parse(source, backend="docling"): force a specific backend, no fallback. Diagnostic mode.Unavailable backends are skipped (logged in the chain), never errored.
Parse-fidelity eval
The routing table above used to be a guess. tests/eval/ turns it into data: a
synthetic fixture corpus (16 documents across digital PDF, scanned/image-only
PDF, table-heavy, multi-column, and raster image classes) with derived
ground-truth markdown, scored against each backend's output on three
OmniDocBench / PubTabNet metrics — text edit distance, table TEDS
(tree-edit-distance similarity), and reading-order. All scores are quality in
[0, 1], higher is better.
Headline result (full table: tests/eval/parse_fidelity_matrix.md):
doc-class | markitdown (text) | docling (text) |
digital_pdf | 0.95 | 0.97 |
table_heavy | 0.93 | 0.89 |
scanned_pdf | 0.00 | 0.87 |
image | 0.00 | 0.90 |
multicolumn | 0.35 | 1.00 |
markitdown is great on clean digital text and digital tables (free, fast, deterministic) but has no OCR — it scores zero on scanned PDFs and images — and it interleaves multi-column layouts. docling wins every class via OCR + layout analysis, at the cost of model-weight downloads. That is the evidence behind the format-preference chain (escalate image/scanned/multi-column to docling first).
Run it:
pip install docling # the escalation backend under test
python tests/eval/generate_fixtures.py # rebuild the corpus (needs fpdf2 + Pillow)
make eval # -> parse_fidelity_matrix.{md,json}The matrix records its provenance (backend + python versions + a fixture-set
hash), so a stale result is visible — regenerate with make eval whenever a
parse backend is upgraded or retuned. It also reports median latency per
backend (the cost axis): the highest-fidelity backend (docling) is far slower
than the default, so the router escalates to it rather than defaulting to it.
The scorer's metric tests are pure-Python and backend-free, so pytest tests/
gates them in CI with only the base (markitdown) install — a routing regression
that breaks the "markitdown has no OCR" assumption fails the build.
Architecture
FastMCP v3.2.3+, stdio transport, Python 3.13+. Registered in [VAULT_ROOT]/.mcp.json. No daemons, no listeners, no model weights downloaded by default.
See SETUP.md for install + per-backend opt-in.
Related MCPs
Same author, same architecture pattern (FastMCP, draft+confirm on writes, vault auto-export where applicable):
slack-mcp — multi-workspace Slack
imessage-mcp — macOS iMessage
whatsapp-mcp — WhatsApp via whatsmeow
apollo-mcp — Apollo.io CRM + sequences
google-workspace-mcp — Gmail / Calendar / Drive / Docs / Sheets
substack-mcp — Substack writing + analytics
Telemetry
This plugin sends a single anonymous install signal to myceliumai.co the first time it loads in a Claude Code session on a given machine.
What is sent:
Plugin name (e.g.
slack-mcp)Plugin version (e.g.
0.1.0)
What is NOT sent:
No user identifiers, names, emails, tokens, or API keys
No file paths, message content, or anything from your work
No IP address is stored after dedup processing
Why: Helps the maintainer know which plugins people actually install, so attention goes to the ones that get used.
Opt out: Set the environment variable MYCELIUM_NO_PING=1 before launching Claude Code. The hook will skip the network call entirely. Already-pinged installs leave a sentinel at ~/.mycelium/onboarded-<plugin> — delete it if you want to reset state.
License
MIT. See LICENSE.
Full install or team version at diazroa.com.
Available Tools
8 toolsbenchmarkB
Run every available backend on the same input, compare results.
Diagnostic tool. Returns one ParseResult per available backend with latency, byte counts, error state, and metadata so you can see at a glance which parser handles a given document best.
Inputs: source (required). Returns: object
chunk_textA
Chunk a markdown document into retrieval-ready pieces.
Picks a doc-type-aware chunker (paper / book / manual / qa / resume
/ table / default) based on document structure. Set doc_type to
force a specific chunker; default "auto" runs structural detection.
Inputs: text (required), doc_type, max_tokens, min_tokens, +1 more. Returns: object
detect_doc_typeA
Run structural heuristics to detect document type.
Useful when you want to know what chunk_text would pick before
actually chunking. Returns the resolved doc_type token.
Inputs: text (required). Returns: object
interpretA
Parse the document, then ask Claude over the parsed markdown.
Use this for "summarize this PDF", "extract every action item", "what does this contract say about termination" style requests. The router parses first (cheap, deterministic), then Claude reads the markdown and answers. Cache hits across calls in the same session reuse the parsed text for free input tokens.
Inputs: source (required), instruction (required), model, backend, +1 more. Returns: object
list_backendsA
Report which parse backends are installed + which are missing.
Returns a list of {name, available, module} entries. Use this to
debug "why did the router fall back to markitdown" by checking
whether docling/llamaparse are actually available.
Inputs: no named parameters. Returns: object
parseA
Convert a document to markdown. Routes across backends automatically.
Inputs: source (required), hints, backend. Returns: object
parse_to_vaultA
Parse a document and write it to the vault as a markdown note.
Replaces the standalone ⚙️ Meta/scripts/markitdown_to_vault.py
shell script: same output shape, but with the router's full audit
trail (which backend ran, fallback chain, latency) baked into the
frontmatter.
Inputs: source (required), backend, overwrite, vault_folder. Returns: object
parse_urlC
Shortcut for parsing an HTTP(S) URL. Same return shape as parse.
Inputs: url (required), backend. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
parse, parse_url, parse_to_vault, and interpret all build on the same underlying parse operation, so an agent could easily select the wrong variant when the target or output destination is not explicitly clear. The descriptions help, but the boundaries between these tools remain somewhat fuzzy.
Most tools follow a predictable snake_case verb_noun pattern such as list_backends, chunk_text, and detect_doc_type. parse_to_vault and single-word verbs like parse, interpret, and benchmark are minor deviations, but the overall naming style is coherent.
Eight tools is well-scoped for a document parsing server with diagnostics, vault integration, and chunking support. Each tool maps to a distinct workflow need, and none feel redundant or like filler.
The toolset covers the full parse-chunk-interpret workflow, plus backend diagnostics and vault output. The main gap is the lack of a batch or multi-document parsing operation, but agents can work around that with repeated calls.
Maintenance
Related MCP Connectors
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Document conversion MCP server: PDF to Markdown, image OCR, spreadsheet parsing.
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
Related MCP Servers
- AlicenseAqualityFmaintenanceAn MCP server that exports PDF documents to markdown format optimized for LLM processing.11BSD 3-Clause
- AlicenseNot gradedqualityDmaintenanceAn MCP server that uses the Docling toolkit to convert various document formats, including PDFs, Office files, images, and audio, into clean Markdown for AI processing. It supports multiple processing pipelines like VLM and ASR with intelligent auto-detection and job queue management.2MIT
- AlicenseNot gradedqualityDmaintenanceGeneric MCP server that exposes Markdown documentation to LLMs, enabling them to search and answer questions about any software documentation.MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that uses Docling to convert PDFs, Office documents, images, audio, and more into clean Markdown for AI processing and RAG pipelines.6-