Email Knowledge Graph

Turn your exported Outlook/Thunderbird emails into a searchable knowledge graph with full-text search, contact relationships, and MCP support for AI assistants.

Zero external dependencies — pure Python stdlib + SQLite FTS5.

Features

• Full-text search — FTS5 with BM25 ranking, snippet highlighting
• Contact graph — who emailed whom, relationship strength
• Web UI — clean local search interface
• MCP protocol — connect AI assistants (opencode, Claude, etc.) directly
• CLI — batch ingest, search, stats from terminal
• Dual format — parses Obsidian-markdown (with YAML frontmatter) and standard .eml files

Quick start

# 1. Point to your emails and run
export EMAIL_GRAPH_DIR=~/path/to/exported/emails
python email_graph.py --ingest

# 2. Search from CLI
python email_graph.py --search "meeting"

# 3. Launch web UI
python email_graph.py --serve
# Open http://localhost:8100

# 4. MCP for AI (stdio mode)
python email_graph.py --stdio

Environment variables

Variable	Default	Description
EMAIL_GRAPH_DIR	./emails	Directory containing .md and .eml files
EMAIL_GRAPH_DATA	./data	Where to store the SQLite database
EMAIL_GRAPH_PORT	8100	HTTP/MCP server port

MCP integration

The server provides three tools via the MCP protocol (HTTP or stdio):

Tool	Description
search_emails	Full-text search with FTS5
get_person_network	Relationship graph for a contact
get_stats	Database statistics

For opencode, add to opencode.json:

{
  "mcpServers": {
    "email-graph": {
      "command": "python",
      "args": ["/path/to/email_graph.py", "--stdio"]
    }
  }
}

Email format

Obsidian markdown

---
sender: John Doe
email: john@example.com
date: 2026-06-15T10:30:00
type: email
---
# Subject line

**From:** John Doe
**Date:** 2026-06-15
**To:** jane@example.com

Body text here...

Standard .eml

Any .eml file exported from Outlook, Thunderbird, etc. is parsed automatically.

License

MIT