Yahoo Mail Server

A Model Context Protocol (MCP) server that enables LLMs to interact with Yahoo Mail. This server allows tools like Gemini CLI or Claude Desktop to read, search, and send emails directly through your Yahoo account.

Features

• Read Emails: Fetch recent messages from your inbox.
• Search Emails: Search for specific messages using keywords, senders, or dates.
• Send Emails: Compose and send emails using Yahoo's SMTP servers.
• Production Ready: Includes Docker support, structured logging, environment validation, and automated tests.

Prerequisites

• Node.js: Version 20 or higher (or Docker).
• Yahoo App Password: For security and ease of use, this server uses Yahoo App Passwords instead of traditional OAuth2 for personal integrations.

Generating a Yahoo App Password

1. Go to your Yahoo Account Security page.
2. Select Generate app password.
3. Choose Other App and name it "Gemini CLI" (or any name you prefer).
4. Copy the 16-character password provided.

Setup

Local Development

1. Clone the repository:

   git clone <repository-url>
   cd yahoo-mail-mcp
   

2. Install dependencies:

   npm install
   

3. Configure Environment Variables: Create a .env file in the root directory:

   [email protected]
   YAHOO_APP_PASSWORD=your-16-character-app-password
   LOG_LEVEL=info
   

4. Build the project:

   npm run build
   

Docker Setup (Recommended for Production)

Build and run the server using Docker to ensure a consistent environment:

1. Build the image:

   docker build -t yahoo-mail-mcp .
   

2. Run the container (for testing build):

   docker run --env-file .env yahoo-mail-mcp
   

Development Commands

• npm run dev: Start the server in development mode.
• npm run lint: Lint the codebase using ESLint.
• npm run format: Format the codebase using Prettier.
• npm run test: Run the test suite using Vitest.
• npm run build: Build the project for production.

Integration with Gemini CLI

1. Register the Server (Local)

gemini mcp add yahoo-mail node $(pwd)/dist/index.js

2. Register the Server (Docker)

gemini mcp add yahoo-mail-docker docker -- run -i --rm --env-file $(pwd)/.env yahoo-mail-mcp

Example Usage

Once registered, you can use natural language to interact with your mail.

Reading Emails

You: "Show me my 5 most recent emails from Yahoo."

Searching Emails

You: "Find any emails from 'Amazon' about my recent order."

Sending Emails

You: "Send an email to @yahoo.com with the subject 'Hello' and the body 'Checking in from my CLI!'"

Project Structure

• src/index.ts: Entry point for the MCP server.
• src/server.ts: MCP server initialization and tool registration.
• src/tools/: Implementation of read_emails, search_emails, and send_email.
• src/lib/:
  • imap.ts: IMAP connection helper.
  • smtp.ts: SMTP connection helper.
  • logger.ts: Winston-based structured logging.
  • config.ts: Zod-based environment validation.

License

ISC