dead-letter MCP server

<!-- mcp-name: io.github.BigCactusLabs/dead-letter -->

dead-letter

Turn .eml email exports into clean, local, LLM-ready Markdown.

dead-letter converts .eml email exports into clean Markdown with YAML front matter — threads split, signatures stripped, attachments extracted, calendars parsed. One file or ten thousand.

Use it to build a readable email archive, move messages into Markdown-based knowledge systems, or prepare email for RAG and LLM pipelines without feeding raw MIME and base64 into your context window. No account, upload, or API key required.

⚡ Try it

If you already have uv, run dead-letter without installing it globally:

uvx --python 3.12 dead-letter convert message.eml

Or install with Homebrew or pip below. Agents and MCP clients can use the client-specific setup in llms-install.md.

🎯 Common use cases

• Email → Markdown archives — turn exported .eml collections into readable, portable Markdown with structured metadata
• RAG and LLM ingestion — normalize message text, thread structure, links, and attachment metadata before chunking or indexing
• Agent workflows — expose conversion and diagnostics directly to Claude, Codex, and other MCP clients
• Knowledge bases — move email into Markdown-first systems such as Obsidian, static archives, or local search pipelines
• Digital preservation — retain human-readable content and useful message structure without depending on one mail client

✨ Features

• Full-fidelity conversion — HTML sanitization, Gmail/Outlook thread segmentation, inline image handling, and calendar event summaries
• CLI — point it at a file or a directory and go
• Local web UI — dark command-center interface with drag-and-drop import, watch mode, conversion grade badges, processing history, and per-job diagnostics
• Inbox/Cabinet workflow — drop .eml files into an Inbox, let dead-letter organize the Markdown bundles into a Cabinet
• Install validation — dead-letter doctor checks your runtime environment
• Conversion report — opt-in JSON report with per-file diagnostics, including attachment referenced/retained counts for automation and audit
• MCP server — integrate with Claude Desktop, Claude Code, Codex, and other MCP clients
• Claude plugin — marketplace install in Claude Code or Cowork with four slash commands (/dead-letter:convert, /dead-letter:summarize, /dead-letter:triage, /dead-letter:cabinet)
• Portable Agent Skill — teaches skill-aware agents when and how to convert .eml files
• Python API — from dead_letter import convert and you're off

🧠 Built for LLM Pipelines

Raw .eml files are noisy input for downstream LLM and retrieval pipelines — MIME headers, multipart boundaries, duplicated HTML/plain bodies, and encoded attachments all get mixed into the text path.

dead-letter normalizes that into Markdown with YAML front matter, so message text and metadata are ready for chunking or indexing without MIME parsing or base64 cleanup. Default convert() and convert_dir() runs write a single .md per message and keep attachment names in front matter.

Shortened. The full README is on GitHub.