Suprasūtā Markdown Notes
Converts documents on your own machine into clean Markdown that AI assistants can read — no upload required.
Convert a single file (
convert_to_markdown): PDF, Word.docx, Excel.xlsx/.xls/.xlsm, PowerPoint.pptx, OpenDocument.odt/.ods, EPUB, CSV/TSV and plain text — saving the.mdbeside the original automatically.Return content your way: short documents come back in full, long ones as a preview plus a saved path; override with
return_content: "full"(all text, costs tokens) or"none"(path only, cheapest).Control the output: pick a destination with
save_to, skip saving withsave: false, and chooseoverwrite: trueor get a numbered filename instead of destroying anything.OCR images locally with
ocr_mode: "offline"(default, nothing uploaded), or"cloud"for Google Gemini accuracy plus chart/diagram descriptions ifGEMINI_API_KEYis set.Transcribe audio — the only feature that can't run locally (needs
ASSEMBLYAI_API_KEY, sends the audio to AssemblyAI).Batch convert several files (
convert_folder_to_markdown) into a directory you choose, with a summary of what succeeded.Keep summaries automatically (
save_summary): write the summary the assistant produced as<name>.summary.mdbeside the document, without being asked.Check capabilities (
list_supported_formats): lists supported extensions and which optional cloud features are configured.Stay private: no account, analytics, telemetry or server of its own; with no API keys set it makes no network connections at all.
Provides cloud OCR via Google's Gemini API, enabling OCR on images and description of charts and diagrams.
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., "@Suprasūtā Markdown Notes Convert D:\reports\quarterly.pdf to markdown and show me the summary"
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.
Suprasūtā Markdown Notes — MCP server
Let Claude, VS Code and Antigravity read any document on your machine — without uploading it.
Created by Narashiman Krishnamurthy
Licence: free for personal, non-commercial use. See LICENSE.md.
What it does
AI assistants can read plain text, and some can read PDFs. None of them read EPUB, OpenDocument, PowerPoint or a scanned image, and all of them do it by uploading your file to a server.
This converts documents on your own machine and hands back Markdown that has been tidied for a model to read — tables promoted to real Markdown tables, deep indentation flattened, code properly fenced.
Documents | PDF, Word |
Images | OCR on the device, with no key and no network |
Audio | Transcription — the one feature that cannot run locally |
Related MCP server: Agent Helper
Tools
Tool | What it does |
| Converts one file and saves the |
| Converts several files into a chosen directory |
| Saves a summary the assistant wrote as |
| Lists the extensions, and which optional cloud features are configured |
About tokens
Converting costs you nothing — it all happens locally. But returning a long document into the conversation does cost tokens, at the same rate as pasting it in by hand.
So a long conversion is saved to disk and only a short preview comes back. A
50-page PDF costs roughly 400 tokens instead of 30,000. Short documents are
returned in full, since they are cheap either way. Ask for
return_content: "full" to override.
Installing
Claude Desktop — the easy way
Download the .mcpb file from
Releases and
double-click it. Claude Desktop installs it and asks which folders it may read,
and optionally for API keys. No Node, no terminal, no JSON.
Claude Desktop — from source
npm install
npm run build
node scripts/install-claude-desktop.mjs --roots "D:\your\documents"Then restart Claude Desktop completely. The script patches the existing config rather than replacing it, and writes a timestamped backup first.
--roots is optional but recommended: it limits which folders the server will
read. Without it, any path the assistant asks for is allowed.
To remove it again: node scripts/install-claude-desktop.mjs --remove
From npm — any MCP host
npm install -g suprasuta-markdown-mcpThen point your host at the suprasuta-markdown-mcp command, or run it without
installing:
{
"servers": {
"suprasuta-markdown": {
"command": "npx",
"args": ["-y", "suprasuta-markdown-mcp"],
"env": { "MARKDOWN_MCP_ROOTS": "D:\\your\\documents" }
}
}
}VS Code and Antigravity
Both read a standard MCP configuration — the block above works as-is.
Antigravity looks in ~/.gemini/config/mcp_config.json, or
.agents/mcp_config.json inside a workspace.
To run a checkout rather than the published package, replace command and
args with node and the absolute path to dist/server.js.
Optional cloud features
Both are dormant until a key is present. Everything else works without either.
Variable | Enables | What leaves your machine |
| Cloud OCR, which can also describe charts and diagrams | The image, to Google |
| Audio transcription | The audio file, to AssemblyAI |
Keys are read from the environment, never written to disk and never logged.
Settings are read once, at start-up. An MCP server is a long-running process, so a key or folder saved while it is running does not reach it until the host restarts. If a key you have just entered reports as not configured, restart the host before looking for anything more complicated.
Development
npm install # .npmrc sets include=dev — do not delete it
npm run build # stages the OCR engine, then bundles with esbuild
npm test # 19 tests against the built bundle
npm run smoke # converts every file in samples/ and reports
npm run typecheckWhy the build is esbuild rather than tsc
src/lib/convert/ is kept byte-identical to the copies in the Windows, web
and Android apps, so that drift can be detected rather than discovered. Those
files use extensionless imports and one Vite-specific ?url import, neither of
which Node's own resolver accepts. esbuild resolves both, so the shared files
never need Node-shaped edits.
The runtime hook
Three things genuinely differ between a browser and Node, and
src/lib/convert/runtime.ts asks the host rather than sniffing for process:
Hook | Why |
| A browser needs URLs and its own worker; Node needs filesystem paths and must not be given the browser worker |
| mammoth reads |
| tesseract's Node build cannot decode a |
Everything else is shared. src/runtime/node.ts supplies the Node answers and
shims exactly one browser global, DOMParser.
A caution learned the hard way: that file used to define
documenttoo, and it broke OCR. tesseract.js sniffed for a DOM, found one, took the browser branch and died onwindow is not defined. Half a browser is worse than none — shim the minimum.
Keeping the copies honest
npm run sync:check # list differences against all three apps
npm run sync:pull web # bring the web app's version in
node scripts/sync-converters.mjs --push webThis package is the canonical copy: it is the only one with the runtime hook
that lets identical files run in both environments, so fixes start here and
flow outward. sync:check reports and exits zero — drift is information, not a
build failure.
Privacy Policy
This software collects nothing. No account, no analytics, no telemetry, and no server of its own — document conversion happens entirely on your machine.
Two optional features send data to a third party, and only when you supply your own API key: cloud image recognition sends the image to Google, and audio transcription sends the audio to AssemblyAI. With no keys configured, the software makes no network connections at all. API keys are read from the environment, never written to disk and never logged.
Full policy, covering collection, storage, retention, third-party sharing and contact details: PRIVACY.md.
Related
Windows app | |
Web app | |
Android | Install the web app from Chrome · older native build, no longer maintained |
Available Tools
4 toolsconvert_folder_to_markdownA
Convert several documents at once and return a summary of what succeeded. Use when the user points at a set of files rather than one.
Inputs: paths (required), output_directory (required).
convert_to_markdownA
Convert a document on this machine to clean Markdown. Handles PDF, Word (.docx), Excel (.xlsx/.xls/.xlsm), PowerPoint (.pptx), OpenDocument text and spreadsheets (.odt/.ods), EPUB, CSV/TSV and plain text. Images are read with OCR, and audio is transcribed. Conversion happens locally and the file is not uploaded, except for the image and audio cases noted in ocr_mode. Prefer this over reading a binary file directly.
The Markdown is SAVED AUTOMATICALLY as a .md file beside the original, so the user does not need to ask. Short documents are also returned in full; long ones come back as a preview plus the saved path, to avoid filling the conversation with tens of thousands of words. If you need more of a long document than the preview shows, call this again with return_content "full".
Inputs: path (required), save, save_to, ocr_mode, +2 more.
list_supported_formatsA
List the file extensions this server can convert, and report which optional cloud features are configured. Call this if a conversion fails as unsupported.
Inputs: no named parameters.
save_summaryA
Save a summary you have written about a document, as a .md file beside it. Call this WITHOUT being asked whenever you summarise, outline or answer a broad question about a document you converted — the user wants the summary kept, not just shown once in the chat. Do not call it for narrow factual lookups, and never invent a summary in order to save one: pass the text you actually produced.
Inputs: summary (required), source_path (required), title.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: convert one document, convert a folder, save a summary, and list supported formats. The only similar pair (single vs. folder conversion) is well differentiated by cardinality, and save_summary is explicitly limited to agent-written summaries rather than document conversion.
All tool names are lowercase snake_case and begin with imperative verbs, making the set predictable. There is a minor stylistic split between the convert_*_to_markdown pattern and plain verb_noun names like save_summary and list_supported_formats, but the overall convention is coherent.
Four tools is ideal for this narrow server: single-file conversion, batch conversion, summary persistence, and format discovery. Each tool earns its place and there is no redundancy.
The conversion workflow is fully covered: agents can convert one file or many, get content back, and handle unsupported formats. The notes side is thinner since save_summary only creates summaries with no server-side way to read, update, or delete them, but this is workable because summaries are saved as .md files on disk.
Maintenance
Related MCP Connectors
Convert PDFs, Office docs, websites and audio into AI-ready Markdown, then search and ask your docs.
Documents to Markdown: PDF, DOCX, PPTX, XLSX, HTML. Scanned PDF pages read by AI.
Convert PDF, Word, Excel and scanned documents to Markdown, tables and RAG chunks. OCR.
Converts PDF, scans, DOCX, XLSX and PPTX to Markdown with tables and page-aware RAG chunks.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA local document processing toolkit for AI agents that extracts text, converts PDFs to Markdown, merges files, extracts tables, and summarizes documents without external API dependencies.3 npmMIT
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to process files locally — OCR images, extract text from PDFs and DOCX, and describe images using local vision models, all without sending data to external services.-
- AlicenseAqualityCmaintenanceConverts documents between Markdown, PDF, DOCX, and HTML locally with AI-friendly Markdown output and secure file access.613 npmMIT
- AlicenseNot gradedqualityCmaintenanceConverts PDFs, Office files, spreadsheets, emails, audio, and more to Markdown locally, enabling AI assistants to read and process them without cloud upload.MIT