eml-archive-converter

Convert .eml files to Markdown + YAML.

Features

• CLI – python eml2md.py --file message.eml or --folder dir/
• FastAPI – HTTP endpoints for single-file and batch (zip) conversion
• MCP server – expose conversion tools to any MCP-compatible client (e.g. Claude Code)

Installation

pip install -e .

CLI Usage

# Single file
python eml2md.py --file path/to/message.eml

# Entire folder
python eml2md.py --folder path/to/maildir --out /tmp/results

Docker

Build and run with Docker Compose:

docker compose up --build

The FastAPI app is available at http://localhost:8000
The MCP server runs inside the container (see Claude Code config below).

API Endpoints

Method	Path	Description
GET	/health	Health check
POST	/convert/file	Upload a .eml file, get back MD + YAML JSON
POST	/convert/folder	Upload a .zip of .eml files, get back a .zip of results

Claude Code MCP Client Configuration

Add the following to your Claude Code MCP client configuration (e.g. ~/.claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "eml-archive-converter": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "eml-archive-converter-eml-converter-1",
        "python",
        "/app/mcp_server.py"
      ]
    }
  }
}

Note: The container name eml-archive-converter-eml-converter-1 is the default name generated by Docker Compose. Adjust it if you use a different project name or service name.

After updating the config, restart Claude Code. The following MCP tools will be available:

Tool	Description
convert_eml_file	Convert a single .eml file (provide path)
convert_eml_folder	Convert all .eml files in a directory (folder, recursive)
list_eml_files	List .eml files in a directory (folder, recursive)

Project Structure

eml2md.py          # CLI entry-point (thin wrapper)
eml2md_lib.py      # Core library – no duplication
api.py             # FastAPI application
mcp_server.py      # MCP server (FastMCP)
pyproject.toml     # Project metadata & dependencies
Dockerfile         # Container image
docker-compose.yml # Orchestration
supervisord.conf   # Runs FastAPI + MCP in one container