Yahoo Mail MCP Server

Yahoo Mail MCP server for Claude and other MCP clients.

This server supports two modes:

• stdio + Yahoo app password for local desktop use
• sse + delegated Yahoo OAuth for remote Claude connector use

The remote OAuth flow is the important part here: the user connects your MCP URL in Claude, Claude starts MCP OAuth, your server redirects the user to Yahoo consent, Yahoo redirects back to your server, and your server finishes the MCP OAuth flow back to Claude. The user never has to paste a Yahoo app password into Claude.

What’s included

• Yahoo IMAP access with OAuth-backed remote auth
• MCP OAuth endpoints for remote connector login
• Yahoo consent redirect flow
• IMAP XOAUTH2 login for per-user mailbox access
• UID-based email operations
• Tools:
  • list_emails
  • read_email
  • search_emails
  • list_folders
  • delete_emails
  • archive_emails
  • mark_as_read
  • mark_as_unread
  • flag_emails
  • unflag_emails
  • move_emails
  • draft_email

Auth model

1. Local mode

Use this when running through stdio.

• Requires YAHOO_EMAIL
• Requires YAHOO_APP_PASSWORD

2. Remote Claude connector mode

Use this when hosting the server over HTTP/SSE.

• Requires YAHOO_CLIENT_ID
• Requires YAHOO_CLIENT_SECRET
• User signs into Yahoo in the browser
• User grants Yahoo Mail permissions
• Claude receives MCP access/refresh tokens from this server
• This server stores Yahoo refresh/access tokens in memory and uses IMAP XOAUTH2

Important production note

Current token/session storage is in-memory.

That means:

• reconnect is required after process restart or redeploy
• multi-instance deployments need a shared store like Redis or a database

If you want true long-lived production sessions across deploys, move:

• pendingYahooAuthorizations
• mcpAuthCodes
• mcpAccessTokens
• mcpRefreshTokens
• yahooSessions

into a persistent shared store.

Yahoo app setup

Create a Yahoo developer app and enable the permissions your server needs.

Recommended permissions:

• OpenID Email
• OpenID Profile (optional but useful)
• Yahoo Mail read access
• Yahoo Mail write access

Default requested scopes in this server:

YAHOO_SCOPES="openid email"

If Yahoo requires approval for restricted mail scopes on your app, complete that in Yahoo Developer first.

Your Yahoo callback URL should point to:

https://your-domain.com/oauth/callback

For local testing:

http://localhost:3000/oauth/callback

Environment variables

Remote OAuth mode

TRANSPORT_MODE=sse
PORT=3000

YAHOO_CLIENT_ID=your-yahoo-client-id
YAHOO_CLIENT_SECRET=your-yahoo-client-secret
YAHOO_SCOPES=openid email

# Optional but recommended behind proxies/platforms
PUBLIC_BASE_URL=https://your-domain.com

Local stdio mode

TRANSPORT_MODE=stdio

YAHOO_EMAIL=your.email@yahoo.com
YAHOO_APP_PASSWORD=your-yahoo-app-password

Quick start

npm install
cp .env.example .env

Run local stdio mode

npm run start:stdio

Run remote SSE mode

npm run start:sse

Claude remote connector setup

After deploying the server:

1. Deploy this repo on Render
2. In Render environment variables, set:

TRANSPORT_MODE=sse
PUBLIC_BASE_URL=https://your-render-service.onrender.com
YAHOO_CLIENT_ID=...
YAHOO_CLIENT_SECRET=...
YAHOO_SCOPES=openid email

3. Add the remote MCP URL in Claude
4. Use your SSE endpoint:

https://your-domain.com/mcp/sse

5. Claude discovers the MCP auth metadata
6. Claude opens the server authorization flow
7. Your server redirects the user to Yahoo
8. User approves Yahoo Mail permissions
9. Yahoo redirects back to your server
10. Your server completes MCP OAuth and Claude marks the connector connected

For your exact use case, yes — this is the intended path:

• deploy once on Render
• use the Render URL in Claude cloud connector
• user clicks connect
• user signs into Yahoo and accepts permissions
• Claude stores the connector session
• later tool calls use Yahoo OAuth without asking the user for an app password

HTTP endpoints

• GET /health
• GET /mcp/sse
• POST /mcp/message
• GET /.well-known/openid-configuration
• GET /.well-known/oauth-authorization-server
• GET /.well-known/oauth-authorization-server/mcp/sse
• GET /.well-known/oauth-protected-resource
• GET /.well-known/oauth-protected-resource/mcp/sse
• POST /register
• GET /oauth/authorize
• POST /oauth/token
• GET /oauth/callback

Local smoke tests

npm run test:health
npm run test:sse

You can also inspect metadata in OAuth mode:

curl http://localhost:3000/.well-known/oauth-authorization-server
curl http://localhost:3000/.well-known/oauth-protected-resource/mcp/sse

Deployment notes

Render / Fly / any HTTPS host

• set TRANSPORT_MODE=sse
• set YAHOO_CLIENT_ID
• set YAHOO_CLIENT_SECRET
• set PUBLIC_BASE_URL
• set Yahoo app callback to https://your-domain.com/oauth/callback
• do not rely on in-memory sessions for multi-instance production

CORS / proxies

The server already enables permissive CORS for remote MCP clients and respects proxy protocol headers.

How the new remote auth works internally

1. Claude hits /mcp/sse
2. Server challenges with WWW-Authenticate and protected resource metadata
3. Claude discovers /oauth/authorize, /oauth/token, /register
4. Server receives MCP auth request
5. Server redirects user to Yahoo
6. Yahoo returns code to /oauth/callback
7. Server exchanges Yahoo code for Yahoo access/refresh tokens
8. Server creates its own MCP auth code for Claude
9. Claude exchanges that code at /oauth/token
10. Claude uses the returned MCP access token on future MCP requests
11. Tool calls use the mapped Yahoo session and IMAP XOAUTH2

Files to check

• server.js
• .env.example
• docker-compose.yml
• render.yaml
• fly.toml

Current limitations

• token/session storage is in-memory
• stdio mode still uses app password, not browser OAuth
• remote Yahoo OAuth depends on your Yahoo app having required mail scopes enabled

Version

Current implementation version: 4.0.0