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 "john@example.com"
# 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 markermlen=<hex>- Message length in hexadecimal[msg]- Message content follows
Running Tests
pytest
Metadata
Release files for pyoeclassic 0.2.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pyoeclassic-0.2.5.tar.gz | 54.9 kB | Without provenance | Details for pyoeclassic-0.2.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyoeclassic-0.2.5-py3-none-any.whl | Python 3 | none | any | Details for pyoeclassic-0.2.5-py3-none-any.whl |
Total release size: 121.5 kB
Release files / pyoeclassic-0.2.5.tar.gz
| Download URL | pyoeclassic-0.2.5.tar.gz |
|---|---|
| Size | 54.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a9902e6f2f4936f95a47b3ca6db206cf0cdb58a09a744d1e3e76604e066487f7
|
|
BLAKE2b-256 checksum How to use checksums |
e405a36f83a86d923c8cb80377783132e5b9344d30947098dbbf823abfe379a7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / pyoeclassic-0.2.5-py3-none-any.whl
| Download URL | pyoeclassic-0.2.5-py3-none-any.whl |
|---|---|
| Size | 66.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d89b384f0440f344f3fcce2eb8a943bd5c2ddc3962623332553f8e6dae0250b4
|
|
BLAKE2b-256 checksum How to use checksums |
1f52706c2f26c4aa10cf2381d618e15d56c2d58d90837504cdbcba87f0e25ce6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Security for pyoeclassic 0.2.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.