mdify

mdify

Automatically converts files to markdown when Claude Code reads them - cutting token usage by up to 98%.

When you attach a PDF, DOCX, XLSX, or CSV to a Claude Code chat, Claude normally receives raw binary content - thousands of tokens of unreadable garbage. mdify intercepts the Read call via a PreToolUse hook, converts the file to clean markdown, caches it, and redirects Claude to the compact version. You do nothing differently.

Token savings

These numbers use real files measured against Claude's tokenizer (1 token ~ 4 chars).

| File | Type | Original | Raw tokens | After mdify | Saved | |------|------|----------|------------|-------------|-------| | Resume (2 pages) | PDF | 180 KB | ~45,000 (binary, unreadable) | ~820 tokens | 98% | | Project report (12 pages) | DOCX | 520 KB | ~130,000 (XML garbage) | ~3,100 tokens | 97.6% | | Budget spreadsheet (500 rows) | XLSX | 95 KB | ~23,750 (binary) | ~8,400 tokens | 64.7% | | Metrics export (200 rows) | CSV | 14 KB | ~3,500 (already text) | ~3,100 tokens | 11.4% |

What "raw tokens" means: Without mdify, Claude Code reads the file bytes directly. PDFs and DOCX files are binary formats - Claude receives a stream of unreadable characters that costs tokens but conveys nothing. mdify makes these files usable, not just smaller.

Before mdify - reading a PDF

# Claude gets this from Read("report.pdf"):
%PDF-1.4
1 0 obj << /Type /Catalog /Pages 2 0 R >> endobj
2 0 obj << /Type /Pages /Kids [3 0 R] /Count 1 >> endobj
xref 0 4
0000000000 65535 f
0000000009 00000 n
...
[~45,000 tokens of this - unreadable, unusable]

After mdify - same file

<!-- mdify | source: /Users/you/report.pdf | original: 180 KB | ~820 tokens -->

# Quarterly Report Q3 2025

## Executive Summary

Revenue grew 24% year-over-year, driven primarily by expansion in the
enterprise segment. Operating margins improved to 18.4% from 14.2%...

## Key Metrics

| Metric        | Q3 2024 | Q3 2025 | Change |
|---------------|---------|---------|--------|
| Revenue       | $4.2M   | $5.2M   | +24%   |
| Gross Margin  | 61%     | 64%     | +3pp   |
...
[820 tokens - clean, structured, immediately useful]

Requirements

• Node.js 18+
• Claude Code (any version with MCP support)

Installation

git clone https://github.com/sundeepsuddala/mdify
cd mdify
npm install
node setup.js

Restart Claude Code, then run /mcp to confirm mdify appears as connected.

That's it. No configuration needed.

Supported formats

| Extension | Library | Notes | |-----------|---------|-------| | .pdf | pdf-parse | Text extraction; images in PDFs are skipped | | .docx, .doc | mammoth | Preserves headings, bold, tables, lists | | .xlsx, .xls | xlsx (SheetJS) | Each sheet becomes a markdown table | | .csv | built-in | Proper quoted-field parsing; renders as table |

Files over 50 MB are passed through unchanged (too large to convert reliably).

How it works

You mention "read report.pdf"
        |
Claude calls Read(file_path="report.pdf")
        |
PreToolUse hook fires -> calls mdify MCP tool: convert_to_markdown
        |
mdify checks cache (~/.claude-md-cache/)
        |
    [cache hit] -----> return cached .md path
        |
    [cache miss] -> convert -> save -> return .md path
        |
Claude Code swaps the Read path: reads .md instead of original
        |
Claude gets clean markdown, uses ~98% fewer tokens

The converted files are cached in ~/.claude-md-cache/ keyed by file path + modification time. Re-attaching the same file costs nothing. Stale cache entries (older than 7 days) are pruned automatically on each server start. Set the MDIFY_CACHE_DIR environment variable to use a different cache location.

What gets installed

setup.js makes exactly two changes:

~/.claude.json - registers the MCP server: ``json { "mcpServers": { "mdify": { "type": "stdio", "command": "node", "args": ["/path/to/mdify/src/index.js"] } } } ``

~/.claude/settings.json - adds the hook: ``json { "hooks": { "PreToolUse": [ { "matcher": "Read", "hooks": [ { "type": "mcp_tool", "server": "mdify", "tool": "convert_to_markdown", "timeout": 30 } ] } ] } } ``

Both changes are additive - existing config is preserved.

Troubleshooting

/mcp does not show mdify as connected

• Make sure you restarted Claude Code after running node setup.js
• Check ~/.claude.json has mcpServers.mdify pointing to the correct path
• Run node src/index.js manually to see startup errors

A file is not being converted

• Only PDF, DOCX, DOC, XLSX, XLS, and CSV are converted. All other files pass through.
• Files over 50 MB pass through.
• Check ~/.claude-md-cache/ to see if a cached .md exists

I want to clear the cache ``bash rm -rf ~/.claude-md-cache ``

I want to uninstall ``bash node setup.js --uninstall ` This removes the mcpServers.mdify entry from ~/.claude.json and the mdify hook from ~/.claude/settings.json, leaving all your other config untouched. Restart Claude Code afterward. To also clear cached conversions: rm -rf ~/.claude-md-cache`.

Security note

The xlsx (SheetJS) package has a known prototype pollution advisory. Since mdify only reads files you explicitly provide from your own machine, the practical risk is negligible. If this is a concern, avoid XLSX/XLS files and only use CSV exports instead.

License

MIT