Integrates with OpenAI Codex Desktop chats by sending email notifications tied to the originating chat UUID and routing email replies back into the active Codex chat.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
简体中文 · Experimental macOS preview · MIT
Send an email notification from a Codex chat, reply from your phone, and route the new reply text back to the originating desktop chat.
This is a small local application with an optional MCP interface. The desktop adapter uses a private, versioned IPC protocol and may need updates after a Codex Desktop upgrade. It is an independent project, not an OpenAI product.
SMTP notifications bound to the real originating chat UUID.
Read-only IMAP polling, matched by email references and a random notification marker.
Learning server-assigned Message-IDs when a provider rewrites outgoing IDs.
Plain-text / HTML reply extraction, common quote removal, loop prevention and deduplication.
Submission into an active desktop turn, with a fresh turn only after an explicit idle response.
CLI, two MCP tools, and an opt-in macOS login service.
The initial scope is one mailbox sending notifications to itself, using the same login and app password for SMTP and IMAP. The monitored inbox must receive the original notification so that rewritten IDs can be learned. Arbitrary external recipients and multiple mailbox accounts are not supported in 0.1.
Automatic notification on every chat completion, crash monitoring, guaranteed delivery, attachments as commands, and multi-user access are not included.
Related MCP server: agent-bridge
Use Python 3.11 or newer on macOS. Keep the checkout and its environment at a stable location if you install a background service from it.
python3 -m venv .venv
. .venv/bin/activate
python -m pip install ".[mcp]"
codex-mail-bridge --versionNo GitHub repository or package-registry publication is required. The base
package has no third-party runtime dependencies; the mcp extra adds the MCP SDK.
codex-mail-bridge init
codex-mail-bridge doctor --networkThe setup asks for your provider's SMTP and IMAP endpoints and hides password entry. Enable these protocols with your provider and use an app password or authorization code where required. Setup does not send mail or install a service. The optional network check performs only an IMAP TLS login; it is not a complete delivery or desktop compatibility check.
For manual configuration, codex-mail-bridge init --example creates a private
template. Edit its placeholder values, then run codex-mail-bridge set-password.
The repository's example contains no credentials.
Connection settings go to ~/.config/codex-mail-bridge/config.json; credentials
go to a separate credentials.json with mode 0600 in that mode-0700 directory.
CODEX_MAIL_BRIDGE_PASSWORD is an alternative for foreground commands. Do not
paste credentials into chat, shell arguments, or this repository.
Start the listener in another terminal:
codex-mail-bridge listenFrom a shell tool inside the target Codex chat, send:
codex-mail-bridge send --title 'Your input is needed' 'Please review the result.'The CLI reads CODEX_THREAD_ID in that shell. Outside Codex, supply the actual
UUID with --thread-id. A missing ID is an error; --one-way explicitly sends
an email without reply routing. Use --dry-run to preview without credentials
or network access.
On your phone, reply directly to that email and write above the quoted text. New text is submitted to the same chat. Default polling is 15 seconds. The Mac must be online, with the desktop app running, signed in, and owning the chat. Replies are ordinary user input and inherit that chat's execution permissions. Read the trust model before enabling the bridge.
codex-mail-bridge mcp-configAdd the printed server table to your existing user-level Codex configuration, preserving other settings, then reload MCP or open a new local chat. Generation does not modify Codex configuration. It prints the active Python interpreter, so invoke it from the environment in which you installed the package.
Tools:
Tool | Input / purpose |
|
|
| Heartbeat and delivery counts; no message contents |
Always provide the current chat's UUID to MCP. A shell tool in that chat can
read CODEX_THREAD_ID; the MCP process is not assumed to know which chat called
it. Never freeze a thread UUID into a global server configuration.
Authoritative Codex setup reference: local MCP configuration.
After configuring a private local credentials file:
codex-mail-bridge service install --dry-run
codex-mail-bridge service install
codex-mail-bridge statusThe opt-in installer creates only org.codexmailbridge.listener for the current
macOS user. It does not register MCP or edit other services. Use --replace
only when updating this project's existing service definition. Keep its Python
environment installed. Shell-only password variables are not copied into the plist.
codex-mail-bridge service uninstallUninstalling the service retains private configuration and history. Remove the
MCP table you added and uninstall the package with python -m pip uninstall codex-mail-bridge when desired. Review and delete the private config/state
directories yourself if you also want to remove credentials and delivery records.
Desktop submission is experimental and macOS-only. See compatibility.
The original prototype received a real mobile reply in an active chat. The standalone package is validated with isolated tests; idle recovery still needs an explicit live end-to-end test on each supported desktop build.
Notifications expire after 14 days. Messages larger than 512 KiB and new reply bodies over 24,000 characters are not forwarded; attachments are not commands.
Failed or uncertain desktop submissions are recorded, not automatically replayed. Check status and logs before manually acting. There is no replay UI.
IMAP reconnects after transient errors. A changed UIDVALIDITY requires manual review; historical messages are not blindly replayed.
This is a single-user correlation mechanism, not cryptographic email-sender authentication or a general-purpose remote execution gateway.
More: configuration, architecture, security, development, local release validation.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Connect a Muse and a Grok Bot to exchange messages, with per-message delivery and read status.
Give an agent its own inbox: send, receive, and pull signup codes from real email.
Capture, inspect, send and assert on webhooks and inbound email from your coding agent.
Give an AI agent its own email address: send, reply, read, and wait for mail.
