Yahoo Mail MCP

A self-hosted MCP server for one Yahoo Mail account. Search and read messages, save drafts, send plain-text email, change read flags, and deliver signed new-mail webhooks.

Runs on Linux, Windows, and macOS with Node.js 22.13 or newer. No Python, Homebrew, Keychain, or Bitwarden installation is required. CI runs synthetic tests on all three operating systems with Node.js 22 and 24.

Quick start

Install Node.js and Git. Generate a Yahoo app password for this connector in your Yahoo account settings; use that password rather than your normal account password. See Yahoo's app-password instructions.

Run these commands in Terminal, a Linux shell, PowerShell, or Command Prompt:

git clone https://github.com/gabeosx/yahoo-mail-mcp.git
cd yahoo-mail-mcp
npm ci --ignore-scripts
npm run configure

Open the generated .env in a text editor and fill in:

YAHOO_EMAIL=your-address@yahoo.com
YAHOO_APP_PW=your-yahoo-app-password

The configure command creates separate random authentication and encryption keys. Keep both values, and keep .env private. It refuses to overwrite an existing configuration.

npm start

The server listens at http://127.0.0.1:8935/mcp. An MCP client must send X-Yahoo-Connector-Token with the value of YAHOO_CONNECTOR_TOKEN. Use a client that supports Streamable HTTP with custom headers, or connect through the optional OpenAI tunnel.

To expose the draft, send, and mark-read tools, set YAHOO_READ_ONLY=false and restart. New installations expose three read tools and the new-mail event. Use Ctrl+C to stop.

Related MCP server: Submail

Tools

Message operations use a UID and uidValidity returned by a list result, so a rebuilt mailbox cannot silently redirect an operation to another message. Reading is limited to 5 MiB messages and 30,000 text characters. Sending attachments and downloading attachments are not implemented.

Draft and send operations require a UUID requestId. Retrying identical content with the same ID returns the original confirmed result. An interrupted or failed write blocks reuse of that ID; inspect Yahoo before choosing a new one. This avoids blindly resending after a timeout. SMTP acceptance means Yahoo accepted the recipients, not that final delivery succeeded.

New-mail events

yahoo.message.created supports mailbox, sender, and subject filters. The server polls Yahoo every 60 seconds while subscriptions exist, persists subscriptions and pending deliveries in SQLite, and signs callbacks using Standard Webhooks. See the event contract and delivery limits.

A subscription starts at the current mailbox position and lasts at most 24 hours. This is a new-mail monitor, without a protocol replay cursor. Expiration or a mailbox UID reset establishes a fresh baseline. Event availability depends on the client's event support; ordinary MCP clients can still use the mail tools.

Configuration

Relative data paths resolve from the repository directory, independent of the process's working directory. Absolute paths are supported, including Windows drive paths on Windows. Store credentials outside source control. Existing environment variables take precedence over the local env file.

For a secret manager or background service that supplies environment variables directly, start with:

node /absolute/path/to/yahoo-mail-mcp/src/server.mjs

On Windows, use a path such as C:\Apps\yahoo-mail-mcp\src\server.mjs. See background operation on each platform. Bitwarden, Keychain, or another secret manager can supply the same environment variables; no provider-specific identifiers are embedded in the server.

Storage and access

This is a single-account server. Anyone holding its connector token can use the exposed tools and create event subscriptions for that account. Tool descriptions ask clients to follow user authorization, but they do not replace the client's own action permissions. Treat email subjects, senders, and bodies as untrusted input.

The listener binds only to IPv4 loopback. The custom token header is checked on every request. The server validates Host and Origin headers and limits request sizes and concurrent requests. OAuth, multi-user hosting, stdio transport, and a public hosted endpoint are outside this release's scope.

Subscription secrets, queued event payloads, and saved write results use AES-256-GCM encryption. Database identifiers, hashes, statuses, and timing metadata are not encrypted. Keep the encryption key with your backup: losing or changing it makes stored payloads unreadable. Keep the same database across restarts to retain send deduplication.

Unix configuration/database files are created with owner-only permissions. Windows uses the directory's inherited ACLs; store the checkout and data in an account-restricted location. The ignored .env contains credentials in plaintext. Encryption at rest does not protect against another process running as your OS user.

Development

npm ci --ignore-scripts
npm run check
npm test

Tests use synthetic mail, fake webhook receivers, temporary databases, and local HTTP listeners. They do not access Yahoo or send real email. CI covers Linux, Windows, and macOS with Node.js 22 and 24. Yahoo read access was checked in the originating private deployment; live sending and end-to-end event delivery are not claimed as verified by this public test suite.

See CONTRIBUTING.md. MIT licensed. This is an independent project, not affiliated with Yahoo or OpenAI.