pyoeclassic 0.2.5

MCP server for OE Classic email — gives AI agents fast full-text search, read/write/move/delete, and send via stored Gmail/Microsoft OAuth

pyoeclassic

MCP server that gives AI agents full read/write/send access to an OE Classic mailbox.

Wire it into Claude, Codex, or any MCP-compatible agent in under a minute. Your agent can then search tens of thousands of emails in milliseconds (Whoosh full-text index), move and delete messages, send email from your existing Gmail and Microsoft accounts using OE Classic's stored OAuth tokens, and trigger Send/Receive — all without touching a browser, all local, no new credentials.

"mcpServers": {
  "oeclassic-email": { "type": "http", "url": "http://127.0.0.1:8093/mcp" }
}

MCP tools

Tool	What your agent can do
email_search	Sub-second full-text search across all folders (Whoosh index)
email_get	Fetch a message by ID with full headers and body
email_stats / email_folders	Mailbox overview — counts, sizes, folder tree
email_move	File a message into any folder
email_delete	Delete a message
email_send_self	Send an HTML message to your local inbox
email_queue_oe_external	Queue outbound mail through OE Classic (reuses stored Gmail / Microsoft OAuth — no new tokens)
email_oe_send_receive	Trigger OE Classic Send/Receive to flush the outbox
email_import_inbox	Inject a message directly into Inbox
email_list_senders	List known sender accounts available for outbound
email_prepare_external	Pre-flight an outbound message before queuing
email_refresh_inbox	Force an inbox refresh

Quick start (MCP server)

pip install "pyoeclassic[all]"
pyoeclassic-build-index          # build Whoosh index on first run
pyoeclassic-mcp --host 127.0.0.1 --port 8093

Add the config snippet above to ~/.claude/settings.json (or your agent's MCP config), restart, and all 12 tools are live.

Python library — Quick Start

from pyoeclassic import Client

# Connect to an identity
client = Client(identity="Testing")

# List folders
for folder in client.folders.list():
    print(f"{folder.name}: {folder.total_count} emails")

# Access emails
inbox = client.emails("Inbox")
print(f"Total: {inbox.count()}, Unread: {inbox.unread_count()}")

# Search emails
results = inbox.search(subject="*report*", limit=10)

# Get full email content
email = inbox.get(1)
print(email.body_text)

# Export emails
inbox.export("backup.jsonl", format="jsonl")

OEC Browser

A simple command-line tool for browsing OE Classic email data:

# Interactive mode (menu-driven)
python oec_browser.py

# List folders and email counts
python oec_browser.py --list

# Show all files in identity folder
python oec_browser.py --all-files

# List detached folders (files not in database)
python oec_browser.py --detached

# Browse a specific folder
python oec_browser.py --folder Inbox

# Browse a detached folder directly
python oec_browser.py --detached-folder "Archive"

# Search by subject or sender
python oec_browser.py --search-subject "report" --search-folder Inbox
python oec_browser.py --search-sender "[e-mail]"

# Analytics
python oec_browser.py --stats              # Folder statistics
python oec_browser.py --top-senders Inbox  # Top senders in folder
python oec_browser.py --top-senders-all    # Top senders across all folders

Interactive Menu Features

• Browse: Folder tree, detached folders, all files
• Search: By subject, sender, or content (single folder or all)
• Analytics: Folder stats, top senders, top domains

CLI

# List identities
pyoeclassic identities

# Show identity info
pyoeclassic info -i Testing

# List folders
pyoeclassic folders list --tree

# Folder operations
pyoeclassic folders attach "MyFolder"
pyoeclassic folders detach 5
pyoeclassic folders status

# Email operations
pyoeclassic emails list -f Inbox
pyoeclassic emails search "*report*" -f Inbox
pyoeclassic emails export backup.jsonl -f Inbox

MCP Service (Internal Install)

The OE Classic search/write MCP server is packaged as optional PyOEClassic features for the local Windows automation setup:

pip install -e ".[all]"
pyoeclassic-mcp --host 127.0.0.1 --port 8093
pyoeclassic-build-index --update

The Windows service wrapper can be installed/refreshed through a local deployment script that runs the packaged service module under a Python environment with pywin32. The service is intentionally local-only (127.0.0.1:8093) and bound to Main Identity.

The local Windows runtime is installed under:

C:\Servers\oeclassic-email-mcp

Use these runtime commands on this workstation:

C:\Servers\oeclassic-email-mcp\refresh.cmd
C:\Servers\oeclassic-email-mcp\remove.cmd

Runtime state is split from source: logs and the search index live under the runtime directory, local secrets and workstation paths live in config\local.env.cmd, and package source remains in the MBX checkout.

External Gmail/Hotmail sending is handled by queueing messages into OE Classic so OE can use its existing account authentication. The packaged MCP does not ship the abandoned direct Gmail API send path.

OE Classic Corruption Recovery

Operational recovery notes are included for agents and operators:

• Human runbook: docs/runbooks/oeclassic-corrupt-mbx-recovery.md
• Packaged LLM card: pyoeclassic/llm/oeclassic-corruption-recovery.md

The short version: stop OE Classic and PythonOEClassicEmailMCP, back up the .mbx/.db pair, repair copied files first, and deploy only after structural verification passes.

Folder Attach/Detach

Archive old folders by detaching them:

from pathlib import Path
from pyoeclassic import Client

client = Client(identity="Testing")

# Detach folder and move files to archive
client.folders.detach_to_archive(
    folder_id=5,
    archive_path=Path("/backups/email_archive")
)

# Re-attach later
client.folders.attach_from_archive(
    name="OldEmails",
    archive_path=Path("/backups/email_archive")
)

Safety

The library protects "Main Identity" from write operations. Test identities (Testing, Testing2, Testing3) are safe for development.

Project Structure

pyoeclassic/           # Main library
  client.py            # Client class
  core/                # Config, database, MBX parser
  operations/          # Folder and email managers
  models/              # Folder and Email models
  cli/                 # Command-line interface
  runtime/             # Packaged Windows service runtime assets

oec_browser.py         # Simple browser tool
examples/              # Example scripts
tests/                 # Test suite
_legacy/               # Old scripts (archived)

MBX File Format

OE Classic MBX files use a specific format:

• [hdr] - Message header marker
• mlen=<hex> - Message length in hexadecimal
• [msg] - Message content follows

Running Tests

pytest