Skip to main content
Glama
jtokib

yahoo-mail-mcp-server

by jtokib
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Hybrid

Yahoo Mail MCP Server

A Model Context Protocol (MCP) server that provides full email management for Yahoo Mail via IMAP. This server supports both local stdio transport (for Claude Desktop) and HTTP/SSE transport (for remote access via Claude.ai).

Features

  • Secure OAuth 2.0 Authentication: Protect your remote MCP server with OAuth 2.0 authorization code flow with PKCE

  • UID-Based Operations: Uses permanent IMAP UIDs that don't change when emails are deleted (v3.0.0+)

  • Full Email Management: Complete email operations with batch processing support

  • Eleven Powerful Tools:

    • list_emails: List recent emails with enriched metadata (size, flags, attachments) and pagination

    • read_email: Read the full content of emails (batch support)

    • search_emails: Advanced search with filters (date ranges, sender, unread status)

    • list_folders: Discover all available IMAP folders

    • delete_emails: Move emails to Trash (soft delete, recoverable)

    • archive_emails: Archive emails for long-term storage

    • mark_as_read: Mark emails as read

    • mark_as_unread: Mark emails as unread

    • flag_emails: Flag emails as important/starred

    • unflag_emails: Remove flag from emails

    • move_emails: Move emails to any folder

  • Enriched Metadata: All emails include UID, size, flags, hasAttachments, and folder information

  • Advanced Search: Filter by date range, sender, unread status, and search across any folder

  • Batch Operations: All management operations support processing multiple emails at once with accurate success/failure tracking

  • Dual Transport Modes:

    • stdio: For local Claude Desktop integration

    • sse: For remote access via HTTP/Server-Sent Events (required for Render.com)

  • Cross-Platform: Works on both Windows and Linux development environments

  • Docker Support: Containerized deployment with Docker and Docker Compose

  • Cloud Ready: Configured for easy deployment to Render.com with OAuth security

Related MCP server: Yahoo Mail MCP Server

Prerequisites

For Local Development

  • Node.js: Version 18.0.0 or higher

  • Yahoo Mail Account: With app-specific password enabled

  • Git: For version control

For Docker Development/Deployment

  • Docker: Latest version

  • Docker Compose: Latest version (included with Docker Desktop on Windows/Mac)

For Render.com Deployment

  • GitHub Account: To host your repository

  • Render.com Account: Free tier available at https://render.com

Quick Start

1. Clone and Setup

# Clone the repository
git clone <your-repo-url>
cd yahoo-mail-mcp-server

# Copy environment template
cp .env.example .env

2. Get Yahoo Mail App Password

  1. Go to https://login.yahoo.com/account/security

  2. Click "Generate app password" or "Manage app passwords"

  3. Select "Other App" and enter "MCP Server"

  4. Copy the generated 16-character password

3. Configure Environment

Edit .env file with your credentials:

YAHOO_EMAIL=your.email@yahoo.com
YAHOO_APP_PASSWORD=your16charpassword
TRANSPORT_MODE=stdio  # or 'sse' for HTTP mode
PORT=3000

4. Install Dependencies

Windows (PowerShell):

npm install

Linux/macOS (Bash):

npm install

5. Run Locally

stdio mode (for Claude Desktop):

npm run start:stdio

SSE mode (for testing HTTP endpoint):

npm run start:sse

Development mode (with auto-reload):

npm run dev

Docker Usage

Build and Run with Docker

Windows (PowerShell):

# Build the image
npm run docker:build

# Run the container
npm run docker:run

# Or use Docker Compose (recommended)
npm run docker:compose:up

# View logs
npm run docker:compose:logs

# Stop containers
npm run docker:compose:down

Linux/macOS (Bash):

# Build the image
npm run docker:build

# Run the container
npm run docker:run

# Or use Docker Compose (recommended)
npm run docker:compose:up

# View logs
npm run docker:compose:logs

# Stop containers
npm run docker:compose:down

Manual Docker Commands

Windows (PowerShell):

# Build
docker build -t yahoo-mail-mcp .

# Run
docker run -p 3000:3000 `
  -e YAHOO_EMAIL=your.email@yahoo.com `
  -e YAHOO_APP_PASSWORD=yourpassword `
  -e TRANSPORT_MODE=sse `
  yahoo-mail-mcp

# Or with Docker Compose
docker-compose up -d

Linux/macOS (Bash):

# Build
docker build -t yahoo-mail-mcp .

# Run
docker run -p 3000:3000 \
  -e YAHOO_EMAIL=your.email@yahoo.com \
  -e YAHOO_APP_PASSWORD=yourpassword \
  -e TRANSPORT_MODE=sse \
  yahoo-mail-mcp

# Or with Docker Compose
docker-compose up -d

Testing the Server

Test Health Endpoint

Windows (PowerShell):

# Using npm script
npm run test:health

# Using curl (if installed)
curl http://localhost:3000/health

# Using PowerShell
Invoke-WebRequest -Uri http://localhost:3000/health | Select-Object -Expand Content

Linux/macOS (Bash):

# Using npm script
npm run test:health

# Using curl
curl http://localhost:3000/health

Test SSE Endpoint

Windows (PowerShell):

# Using npm script
npm run test:sse

# Using curl
curl http://localhost:3000/mcp/sse

# Using PowerShell
Invoke-WebRequest -Uri http://localhost:3000/mcp/sse

Linux/macOS (Bash):

# Using npm script
npm run test:sse

# Using curl
curl http://localhost:3000/mcp/sse

Deploying to Render.com

Step 1: Prepare Your Repository

Windows (PowerShell):

# Initialize git (if not already done)
git init

# Add all files
git add .

# Commit
git commit -m "Initial commit: Yahoo Mail MCP Server"

# Create GitHub repository at https://github.com/new
# Then push to GitHub
git remote add origin https://github.com/yourusername/yahoo-mail-mcp-server.git
git branch -M main
git push -u origin main

Linux/macOS (Bash):

# Initialize git (if not already done)
git init

# Add all files
git add .

# Commit
git commit -m "Initial commit: Yahoo Mail MCP Server"

# Create GitHub repository at https://github.com/new
# Then push to GitHub
git remote add origin https://github.com/yourusername/yahoo-mail-mcp-server.git
git branch -M main
git push -u origin main

Step 2: Deploy to Render

  1. Sign up/Login to Render.com

  2. Connect GitHub Repository

    • Click "New +" button in top right

    • Select "Web Service"

    • Click "Connect GitHub" and authorize Render

    • Select your yahoo-mail-mcp-server repository

  3. Configure the Service

    • Name: yahoo-mail-mcp-server (or your preferred name)

    • Runtime: Docker

    • Region: Choose closest to you (Oregon, Frankfurt, Singapore, Ohio)

    • Branch: main

    • Plan: Free (or Starter for production)

  4. Set Environment Variables

    In the "Environment" section, click "Add Environment Variable" and add:

    Key

    Value

    How to Generate

    NODE_ENV

    production

    -

    TRANSPORT_MODE

    sse

    -

    YAHOO_EMAIL

    your.email@yahoo.com

    Your Yahoo email address

    YAHOO_APP_PASSWORD

    your16charpassword

    See "Get Yahoo Mail App Password" section

    OAUTH_CLIENT_ID

    32-char-hex-string

    Run: openssl rand -hex 16

    OAUTH_CLIENT_SECRET

    64-char-hex-string

    Run: openssl rand -hex 32

    Important:

    • Mark YAHOO_EMAIL, YAHOO_APP_PASSWORD, OAUTH_CLIENT_ID, and OAUTH_CLIENT_SECRET as "Secret"

    • PORT is automatically set by Render, don't add it manually

    • Save the OAuth credentials - you'll need them to configure Claude Desktop

  5. Deploy

    • Click "Create Web Service"

    • Render will automatically build and deploy your Docker container

    • Wait for deployment to complete (first build takes 5-10 minutes)

  6. Get Your Service URL

    • Once deployed, you'll get a URL like: https://yahoo-mail-mcp-server.onrender.com

    • Test it by visiting: https://yahoo-mail-mcp-server.onrender.com/health

Step 3: Connect to Claude Desktop

Note: Remote MCP servers require a Claude Pro, Max, Team, or Enterprise plan.

  1. Open Claude Desktop

    • Launch the Claude Desktop app on your computer

  2. Add MCP Connector

    • Click on your profile icon or menu

    • Select "Settings"

    • Navigate to "Connectors" section

    • Click "Add Custom Connector"

  3. Configure the Connector

    • Name: Yahoo Mail

    • URL: https://your-service-name.onrender.com/mcp/sse

    Example:

    https://yahoo-mail-mcp-server.onrender.com/mcp/sse

  4. Configure OAuth Authentication

    • Click "Advanced Settings" ⚙️

    • Enter the OAuth credentials from Step 4:

      • OAuth Client ID: The value from OAUTH_CLIENT_ID environment variable

      • OAuth Client Secret: The value from OAUTH_CLIENT_SECRET environment variable

  5. Save and Test

    • Click "Add" or "Save"

    • Claude Desktop will authenticate using OAuth 2.0

    • If successful, you'll see the connector active

    • You can now use Yahoo Mail tools in your conversations!

Step 4: Using the MCP Server in Claude.ai

Once connected, you can use these tools in your conversations:

Can you list my recent emails?

Can you read email number 5?

Can you search for emails from john@example.com?

Troubleshooting

Common Issues

1. "Authentication failed" error

Solution: Verify your app-specific password

  • Make sure you're using an app-specific password, not your regular Yahoo password

  • Generate a new app-specific password at https://login.yahoo.com/account/security

  • Check for typos in your .env file or Render environment variables

2. Docker build fails on Windows

Solution: Check Docker Desktop settings

  • Ensure Docker Desktop is running

  • Check that WSL2 is enabled (Settings > General > Use WSL2 based engine)

  • Verify file sharing is enabled (Settings > Resources > File Sharing)

3. Port 3000 already in use

Solution: Change the port

Windows (PowerShell):

$env:PORT=3001; npm run start:sse

Linux/macOS (Bash):

PORT=3001 npm run start:sse

Or edit .env:

PORT=3001

4. Render deployment fails

Solution: Check the logs

  • Go to your Render dashboard

  • Click on your service

  • Click "Logs" tab

  • Look for error messages

  • Common issues:

    • Missing environment variables

    • Incorrect Dockerfile path

    • Build timeout (increase build timeout in settings)

5. SSE connection drops

Solution: Render free tier limitations

  • Free tier services sleep after 15 minutes of inactivity

  • First request after sleep takes 30-60 seconds to wake up

  • Upgrade to Starter plan ($7/month) for always-on service

6. IMAP connection timeout

Solution: Check Yahoo Mail IMAP settings

  • Ensure IMAP is enabled in Yahoo Mail settings

  • Go to Yahoo Mail > Settings > More Settings > Mailboxes

  • Verify IMAP access is allowed

  • Check firewall settings aren't blocking port 993

Windows-Specific Issues

Line Ending Problems

If you see errors about line endings:

PowerShell:

# Configure git to handle line endings correctly
git config --global core.autocrlf input

# Re-clone the repository
git clone <your-repo-url>

npm Scripts Not Working

If cross-platform scripts fail:

PowerShell:

# Install cross-env globally
npm install -g cross-env

# Or run scripts directly
node server.js

Linux-Specific Issues

Permission Errors with Docker

Bash:

# Add user to docker group
sudo usermod -aG docker $USER

# Logout and login again, or run:
newgrp docker

# Test
docker ps

Environment Variables Reference

Variable

Required

Default

Description

YAHOO_EMAIL

Yes

-

Your Yahoo Mail email address

YAHOO_APP_PASSWORD

Yes

-

16-character app-specific password from Yahoo

OAUTH_CLIENT_ID

Yes (Remote)

-

OAuth 2.0 client ID for MCP server authentication (generate with openssl rand -hex 16)

OAUTH_CLIENT_SECRET

Yes (Remote)

-

OAuth 2.0 client secret for MCP server authentication (generate with openssl rand -hex 32)

TRANSPORT_MODE

No

stdio

Transport mode: stdio or sse

PORT

No

3000

Port for SSE mode (auto-set by Render)

NODE_ENV

No

development

Environment: development or production

Note: OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET are only required for remote deployments (Render.com). Local stdio mode doesn't require OAuth.

Available npm Scripts

Script

Description

Cross-Platform

npm start

Start server (stdio mode)

✅

npm run start:stdio

Start in stdio mode

✅

npm run start:sse

Start in SSE mode

✅

npm run dev

Development mode with auto-reload

✅

npm run docker:build

Build Docker image

✅

npm run docker:run

Run Docker container

✅

npm run docker:compose:up

Start with Docker Compose

✅

npm run docker:compose:down

Stop Docker Compose

✅

npm run docker:compose:logs

View Docker Compose logs

✅

npm run test:health

Test health endpoint

✅

npm run test:sse

Test SSE endpoint

✅

Project Structure

yahoo-mail-mcp-server/
├── server.js                 # Main server code
├── package.json             # Node.js dependencies and scripts
├── Dockerfile               # Docker build configuration
├── docker-compose.yml       # Docker Compose configuration
├── render.yaml              # Render.com deployment config
├── .env.example             # Environment variable template
├── .env                     # Your local environment variables (gitignored)
├── .dockerignore            # Files to exclude from Docker build
├── .gitignore               # Files to exclude from git
├── .gitattributes           # Git line ending configuration
└── README.md                # This file

Security Best Practices

  1. OAuth 2.0 Protection (Remote Deployments)

    • Server requires OAuth 2.0 authentication for all MCP requests

    • Uses authorization code flow with PKCE (Proof Key for Code Exchange)

    • Only clients with correct credentials can access your emails

    • Generate strong random credentials: openssl rand -hex 16 and openssl rand -hex 32

    • Store credentials securely in Render dashboard (marked as "Secret")

  2. Never commit credentials

    • .env file is gitignored

    • Always use .env.example as template

    • Set sensitive values in Render dashboard

    • Never share OAuth credentials publicly

  3. Use app-specific passwords

    • Never use your main Yahoo password

    • Generate new passwords for each service

    • Revoke unused passwords regularly

    • App passwords can be revoked without changing your main password

  4. Email management operations

    • All modification operations are reversible (soft delete, not permanent)

    • Deleted emails are moved to Trash folder (recoverable within 7 days for free accounts)

    • Archive, flag, and read status changes are non-destructive

    • Move operations preserve email content and metadata

    • No send operations - server cannot send emails on your behalf

  5. HTTPS in production

    • Render.com provides free SSL certificates

    • All traffic is encrypted (TLS/SSL)

    • IMAP connection uses TLS

    • OAuth tokens transmitted securely

Development Workflow

Making Changes

Windows (PowerShell):

# 1. Make your changes to server.js

# 2. Test locally
npm run dev

# 3. Test with Docker
npm run docker:compose:up

# 4. Commit and push
git add .
git commit -m "Description of changes"
git push origin main

# 5. Render automatically deploys the changes

Linux/macOS (Bash):

# 1. Make your changes to server.js

# 2. Test locally
npm run dev

# 3. Test with Docker
npm run docker:compose:up

# 4. Commit and push
git add .
git commit -m "Description of changes"
git push origin main

# 5. Render automatically deploys the changes

Viewing Logs

Local Development:

# The server logs to stderr
npm run start:sse

Docker:

npm run docker:compose:logs

Render.com:

  • Go to your service dashboard

  • Click "Logs" tab

  • Real-time logs appear here

API Endpoints

When running in SSE mode, the server exposes these endpoints:

Endpoint

Method

Description

/

GET

API information and available tools

/health

GET

Health check (returns status, version, timestamp)

/mcp/sse

GET

Server-Sent Events endpoint for MCP (requires OAuth token)

/mcp/message

POST

Message endpoint for MCP communication (requires OAuth token)

/.well-known/oauth-authorization-server

GET

OAuth 2.0 server metadata (RFC 8414)

/.well-known/openid-configuration

GET

OpenID Connect discovery endpoint

/oauth/authorize

GET

OAuth 2.0 authorization endpoint

/oauth/token

POST

OAuth 2.0 token endpoint

Example Health Check Response

{
  "status": "ok",
  "service": "yahoo-mail-mcp",
  "version": "1.0.0",
  "timestamp": "2025-01-11T12:34:56.789Z"
}

Breaking Changes & Migration Guide

⚠️ v3.0.0 Breaking Changes

Version 3.0.0 introduces UID-based operations which fundamentally changes how you interact with emails. This is a breaking change that requires updating your code.

What Changed

1. Parameter Rename: sequenceNumbers → uids

All email management tools now use uids (permanent identifiers) instead of sequenceNumbers (temporary positions):

// ❌ v2.x (OLD - sequence numbers)
read_email({ sequenceNumbers: [1, 2, 3] })
delete_emails({ sequenceNumbers: [5] })

// ✅ v3.0.0 (NEW - UIDs)
read_email({ uids: [510867, 510866, 510862] })
delete_emails({ uids: [510867] })

2. Response Format: Plain Text → JSON

All tools now return structured JSON instead of plain text:

// ❌ v2.x response
"Email 1 of 10..."

// ✅ v3.0.0 response
{
  "emails": [...],
  "totalCount": 10,
  "returned": 10
}

3. New Required Workflow

You must now get UIDs from list_emails or search_emails before performing operations:

// Step 1: Get UIDs
const result = list_emails({ count: 10 });
// Returns: { emails: [{ uid: 510867, ... }, { uid: 510866, ... }] }

// Step 2: Use UIDs for operations
const uidsToDelete = [510867, 510866];
delete_emails({ uids: uidsToDelete });

Why UIDs Are Better

Sequence Numbers (v2.x):

  • ❌ Change when emails are deleted

  • ❌ Position-based (email #1, #2, #3)

  • ❌ Can become invalid between operations

  • ❌ Cause confusion and errors

UIDs (v3.0.0):

  • ✅ Permanent identifiers assigned by IMAP server

  • ✅ Never change, even when other emails are deleted

  • ✅ Always valid until email is permanently deleted

  • ✅ Reliable for batch operations

Migration Checklist

  • Update all tool calls to use uids parameter instead of sequenceNumbers

  • Update code to get UIDs from list_emails or search_emails first

  • Update code to handle JSON responses instead of plain text

  • Test batch operations to ensure all UIDs are processed (v3.0.0 fixes critical batch bug)

  • Review new features: pagination, enriched metadata, advanced search, folder support

New Features in v3.0.0

  1. Enriched Metadata: All emails include uid, size, flags, hasAttachments

  2. Pagination: list_emails supports offset and limit parameters

  3. Advanced Search: search_emails supports date ranges, sender filter, unread-only

  4. Folder Support: All tools support folder parameter (default: INBOX)

  5. list_folders: New tool to discover available IMAP folders

  6. Accurate Batch Operations: Fixed critical bug where only first UID was processed

  7. Enhanced Error Handling: Better timeout and connection error messages

MCP Tools

list_emails

List recent emails with enriched metadata (UID, size, flags, attachments) and pagination support.

Parameters:

  • count (optional): Number of emails to retrieve (default: 10, max: 50)

  • folder (optional): Folder to list from (default: 'INBOX'). Use list_folders to see available folders

  • offset (optional): Number of emails to skip for pagination (default: 0)

Response: JSON with emails array containing enriched metadata for each email:

  • uid: Permanent IMAP UID (use this for all operations)

  • sequenceNumber: Position in folder (for reference only, don't use for operations)

  • from: Sender address

  • subject: Email subject

  • date: Date in RFC 2822 format

  • size: Email size in bytes

  • flags: Array of IMAP flags (e.g., ['\\Seen'], ['\\Flagged'])

  • hasAttachments: Boolean indicating if email has attachments

Examples:

// List 20 most recent emails
list_emails({ count: 20 })

// List emails with pagination (skip first 10)
list_emails({ count: 10, offset: 10 })

// List emails from Sent folder
list_emails({ count: 15, folder: "Sent" })

read_email

Read the full content of emails using UIDs (supports batch reading).

Parameters:

  • uids (required): Array of UIDs to read (get UIDs from list_emails or search_emails)

  • folder (optional): Folder containing the emails (default: 'INBOX')

Response: JSON with enriched email data including body content

Examples:

// Read a single email
read_email({ uids: [510867] })

// Read multiple emails
read_email({ uids: [510867, 510866, 510862] })

// Read email from Sent folder
read_email({ uids: [510867], folder: "Sent" })

search_emails

Advanced search with filters for date ranges, sender, and unread status.

Parameters:

  • query (optional): Search term for subject or sender (can be empty for date-only searches)

  • count (optional): Number of results to return (default: 10, max: 50)

  • dateFrom (optional): Filter emails from this date onwards (ISO 8601 or RFC 2822 format)

  • dateTo (optional): Filter emails up to this date (ISO 8601 or RFC 2822 format)

  • sender (optional): Filter by specific sender email address or name

  • unreadOnly (optional): Only return unread emails (default: false)

  • folder (optional): Folder to search in (default: 'INBOX')

Response: JSON with emails array, totalMatches, returned, query, filters, and folder

Examples:

// Basic search
search_emails({ query: "invoice", count: 15 })

// Search unread emails only
search_emails({ query: "meeting", unreadOnly: true })

// Search by date range
search_emails({ dateFrom: "2025-01-01", dateTo: "2025-01-31" })

// Search by sender
search_emails({ sender: "boss@company.com" })

// Combined filters
search_emails({
  query: "report",
  sender: "team@company.com",
  dateFrom: "2025-01-15",
  unreadOnly: true
})

list_folders

Discover all available IMAP folders in your Yahoo Mail account.

Parameters: None

Response: JSON with array of folder objects containing name, path, delimiter, and children

Example:

// List all folders
list_folders()

// Example response:
// {
//   "folders": [
//     { "name": "INBOX", "path": "INBOX" },
//     { "name": "Sent", "path": "Sent" },
//     { "name": "Trash", "path": "Trash" },
//     { "name": "Archive", "path": "Archive" }
//   ]
// }

delete_emails

Move emails to Trash folder using UIDs (soft delete - emails can be recovered).

Parameters:

  • uids (required): Array of UIDs to delete (get UIDs from list_emails or search_emails)

  • folder (optional): Source folder (default: 'INBOX')

Response: Success/failure message with accurate count of processed emails

Examples:

// Delete a single email
delete_emails({ uids: [510867] })

// Delete multiple emails
delete_emails({ uids: [510867, 510866, 510862, 510856] })

// Delete from Sent folder
delete_emails({ uids: [510867], folder: "Sent" })

archive_emails

Move emails to Archive folder using UIDs for long-term storage.

Parameters:

  • uids (required): Array of UIDs to archive

  • folder (optional): Source folder (default: 'INBOX')

Response: Success/failure message with accurate count of processed emails

Examples:

// Archive a single email
archive_emails({ uids: [510867] })

// Archive multiple emails
archive_emails({ uids: [510867, 510866, 510862, 510851] })

mark_as_read

Mark emails as read using UIDs by adding the Seen flag.

Parameters:

  • uids (required): Array of UIDs to mark as read

  • folder (optional): Folder containing the emails (default: 'INBOX')

Response: Success/failure message with accurate count of processed emails

Examples:

// Mark a single email as read
mark_as_read({ uids: [510867] })

// Mark multiple emails as read
mark_as_read({ uids: [510867, 510866, 510862, 510851, 510865] })

mark_as_unread

Mark emails as unread using UIDs by removing the Seen flag.

Parameters:

  • uids (required): Array of UIDs to mark as unread

  • folder (optional): Folder containing the emails (default: 'INBOX')

Response: Success/failure message with accurate count of processed emails

Examples:

// Mark a single email as unread
mark_as_unread({ uids: [510867] })

// Mark multiple emails as unread
mark_as_unread({ uids: [510869, 510867, 510866] })

flag_emails

Flag emails as important/starred using UIDs by adding the Flagged flag.

Parameters:

  • uids (required): Array of UIDs to flag

  • folder (optional): Folder containing the emails (default: 'INBOX')

Response: Success/failure message with accurate count of processed emails

Examples:

// Flag a single email
flag_emails({ uids: [510867] })

// Flag multiple emails
flag_emails({ uids: [510851, 510865, 510864] })

unflag_emails

Remove flag/star from emails using UIDs by removing the Flagged flag.

Parameters:

  • uids (required): Array of UIDs to unflag

  • folder (optional): Folder containing the emails (default: 'INBOX')

Response: Success/failure message with accurate count of processed emails

Examples:

// Unflag a single email
unflag_emails({ uids: [510867] })

// Unflag multiple emails
unflag_emails({ uids: [510867, 510866, 510862] })

move_emails

Move emails to a specified folder using UIDs.

Parameters:

  • uids (required): Array of UIDs to move

  • folderName (required): Name of the destination folder (e.g., "Work", "Personal", "Archive")

  • sourceFolder (optional): Source folder (default: 'INBOX')

Response: Success/failure message with accurate count of processed emails

Examples:

// Move a single email to Work folder
move_emails({ uids: [510867], folderName: "Work" })

// Move multiple emails to Personal folder
move_emails({ uids: [510867, 510866, 510862], folderName: "Personal" })

// Move from Sent to Archive
move_emails({ uids: [510867], folderName: "Archive", sourceFolder: "Sent" })

Performance Considerations

Render.com Free Tier

  • Sleep after inactivity: Services sleep after 15 minutes of no requests

  • Wake-up time: First request takes 30-60 seconds

  • Monthly hours: 750 hours/month (enough for moderate use)

  • Upgrade: $7/month for Starter plan (always-on)

IMAP Performance

  • Connection pooling: Each request creates a new IMAP connection

  • Timeout: 30 seconds for connection and auth

  • Rate limiting: Yahoo may throttle excessive requests

  • Recommendation: Cache results on client side when possible

Cross-Platform Compatibility

This project is designed to work seamlessly on:

  • Windows 10/11 with PowerShell or Command Prompt

  • Linux (Ubuntu, Debian, Fedora, etc.)

  • macOS (Intel and Apple Silicon)

  • Docker Desktop (Windows, Mac, Linux)

  • WSL2 (Windows Subsystem for Linux)

Line Endings

  • .gitattributes ensures LF line endings in repository

  • Works correctly on Windows (CRLF) and Linux (LF)

  • Docker uses LF inside containers

Path Handling

  • All paths use forward slashes in code

  • path.join() used for cross-platform compatibility

  • Works with Windows backslashes and Unix forward slashes

Contributing

  1. Fork the repository

  2. Create a feature branch: git checkout -b feature-name

  3. Make your changes

  4. Test on both Windows and Linux (if possible)

  5. Commit: git commit -am "Add feature"

  6. Push: git push origin feature-name

  7. Create a Pull Request

License

MIT License - See LICENSE file for details

Support

Changelog

v3.0.0 (2025-01-18) - UID Migration

BREAKING CHANGES:

  • All tools now use uids parameter instead of sequenceNumbers

  • Response format changed from plain text to structured JSON

  • UIDs are permanent identifiers that don't change when emails are deleted

New Features:

  • Enriched metadata: All emails include uid, size, flags, hasAttachments

  • Pagination support: list_emails accepts offset and limit parameters

  • Advanced search filters: dateFrom, dateTo, sender, unreadOnly parameters

  • Folder support: All tools accept folder parameter (default: INBOX)

  • New tool: list_folders to discover available IMAP folders

  • Enhanced error handling: Better timeout and connection error messages with Render spindown detection

Bug Fixes:

  • CRITICAL: Fixed batch operations bug where only first UID was processed

  • All batch operations now accurately process every UID in the array

  • Success/failure messages now report exact counts of processed emails

Migration Guide:

  • Replace sequenceNumbers with uids in all tool calls

  • Get UIDs from list_emails or search_emails responses

  • Update code to handle JSON responses instead of plain text

  • See "Breaking Changes & Migration Guide" section above for details

v2.0.1 (2025-01-17)

  • Fixed: Enhanced input validation for all email operations

  • Added shared validation helper to prevent IMAP errors with invalid sequence numbers

  • Improved error messages for better debugging

v2.0.0 (2025-01-16)

  • Breaking Change: read_email now uses sequenceNumbers (array) instead of sequenceNumber (single number)

  • Added full email management with batch operations support

  • Seven new tools: delete_emails, archive_emails, mark_as_read, mark_as_unread, flag_emails, unflag_emails, move_emails

  • All modification operations support batch processing

  • Enhanced security with reversible operations (soft delete, no permanent deletion)

v1.0.0 (2025-01-11)

  • Initial release

  • Support for stdio and SSE transports

  • Docker and Docker Compose support

  • Render.com deployment configuration

  • Cross-platform compatibility (Windows/Linux)

  • Three core tools: list_emails, read_email, search_emails

Acknowledgments

FAQ

Q: Can I use this with Gmail or other email providers?

A: Currently, this server is configured for Yahoo Mail. To support other providers, you'd need to modify the IMAP configuration in server.js (lines 166-179).

Q: Is this safe to use with my email account?

A: Yes! The server uses app-specific passwords (not your main password) and all modification operations are reversible. Delete operations move emails to Trash (recoverable), and the server never permanently deletes emails or sends emails on your behalf.

Q: How much does it cost to run on Render?

A: The free tier provides 750 hours/month, which is enough for moderate use. For always-on service, the Starter plan is $7/month.

Q: Can I run this on other cloud platforms?

A: Yes! The Docker configuration works on any platform that supports Docker containers (AWS ECS, Google Cloud Run, Azure Container Instances, Heroku, Fly.io, etc.).

Q: Do I need to keep my computer running?

A: No! Once deployed to Render.com (or another cloud platform), the server runs independently in the cloud.

Q: How do I update the server after deployment?

A: Simply push your changes to GitHub. Render automatically detects the push and redeploys the service.

Q: Can multiple people use the same deployed server?

A: The server connects to a single Yahoo Mail account (the one configured in environment variables). Each user would need their own deployment for their own email account.

Q: What if I forget my app-specific password?

A: You can generate a new one at https://login.yahoo.com/account/security/app-passwords and update it in your Render environment variables (Settings > Environment).

Next Steps

After successful deployment:

  1. ✅ Test the health endpoint

  2. ✅ Connect to Claude.ai

  3. ✅ Try listing your emails

  4. ✅ Read a few emails

  5. ✅ Search your inbox

  6. 🎉 Enjoy your Yahoo Mail MCP server!

Happy Coding! If you have questions or issues, please open an issue on GitHub.

Available Tools

11 tools
archive_emailsA

Move emails to Archive folder using UIDs for long-term storage. UIDs are permanent identifiers.

ParametersJSON Schema
NameRequiredDescriptionDefault
uidsYesArray of UIDs to archive
folderNoSource folder (default: INBOX)INBOX

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the burden. It discloses that the operation uses UIDs and that UIDs are permanent, which implies the operation is based on stable identifiers. However, it does not state whether the source folder is affected (e.g., are emails removed from source? It says 'move', implying yes), nor any auth requirements, rate limits, or reversibility. The description is minimally transparent but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, each sentence serves a distinct purpose. No fluff or repetition. It is front-loaded with the primary action and clearly structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 2-parameter tool with no output schema, the description is adequate but not complete. It lacks guidance on return values, side effects (e.g., does it delete from source?), and how it differs from move_emails. Given the presence of similar siblings, more context would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both parameters. The description adds minimal extra meaning: 'UIDs are permanent identifiers' provides context for the uids parameter, but does not explain the folder parameter beyond what the schema says. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Move emails'), the destination ('Archive folder'), and the method ('using UIDs'). It also clarifies that UIDs are permanent identifiers, which is helpful. This distinguishes it from siblings like delete_emails or move_emails (which allow arbitrary folders).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool versus its siblings (e.g., move_emails, delete_emails). There is no mention of prerequisites, context, or alternatives. The user must infer usage from the name and description alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_emailsA

Move emails to Trash folder using UIDs (soft delete, recoverable). UIDs are permanent identifiers.

ParametersJSON Schema
NameRequiredDescriptionDefault
uidsYesArray of UIDs to delete
folderNoSource folder (default: INBOX)INBOX

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action is a move to Trash and recoverable, which is transparent, but omits details like authorization requirements, side effects, or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences, front-loading the core action and key characteristic ('soft delete, recoverable'). Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with two parameters and no output schema, the description covers the essential behavior. However, it lacks details on return values, error conditions, or whether UIDs are global or folder-specific, leaving minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides descriptions for both parameters (uids and folder), covering 100% of the schema. The description adds that UIDs are permanent identifiers, which is helpful but not essential beyond the schema's description of 'Array of UIDs to delete'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the action ('Move emails to Trash folder'), the method ('using UIDs'), and the nature ('soft delete, recoverable'), distinguishing it from permanent deletion or archiving. This differentiates it from sibling tools like archive_emails and move_emails.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies that the tool is for soft deletion via UIDs, but does not explicitly state when to use it versus alternatives like 'archive_emails' or 'move_emails' for moving to custom folders. No direct guidance on exclusions or prerequisites is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

flag_emailsA

Flag emails as important/starred using UIDs. UIDs are permanent identifiers.

ParametersJSON Schema
NameRequiredDescriptionDefault
uidsYesArray of UIDs to flag
folderNoFolder containing emails (default: INBOX)INBOX

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided. The description describes a mutation operation ('flag') but does not disclose behavioral traits such as reversibility, whether previous flags are affected, or any rate limits. Given the absence of annotations, the description should provide more context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first defines the action, second explains a key property of UIDs. Very concise and front-loaded with no unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with two straightforward parameters and no output schema. The description covers the core action and UID usage, but lacks details on cross-folder behavior or interaction with sibling tools like marking as read. It is adequate but not exhaustive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds a note about UIDs being permanent identifiers, reinforcing the 'uids' parameter's significance, but adds no further meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Flag emails as important/starred') and the resource ('emails'). It specifies using UIDs, which are permanent identifiers, distinguishing it from other tools like unflag_emails.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies using UIDs for reliable flagging ('UIDs are permanent identifiers'), but it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_emailsA

List recent emails from a Yahoo Mail folder. Returns UIDs (permanent identifiers) and enriched metadata including size, flags, and attachment status.

ParametersJSON Schema
NameRequiredDescriptionDefault
countNoNumber of emails to retrieve (default: 10, max: 50)
folderNoFolder to list emails from (default: INBOX). Use list_folders to see available folders.INBOX
offsetNoNumber of emails to skip (for pagination, default: 0)

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the burden. It mentions returns metadata but does not disclose side effects (e.g., read-only), pagination behavior beyond the offset parameter, or rate limits. The 'recent emails' claim is vague.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words, front-loaded with the primary action and result. Efficiently conveys necessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 3 parameters, no output schema, and no annotations, the description covers basic purpose and parameters but lacks details on how to interpret the returned metadata or the definition of 'recent'. It is adequate but incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. The description adds helpful context for the folder parameter ('Use list_folders to see available folders') and clarifies the count default and max. This justifies a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (list), resource (emails), source (Yahoo Mail folder), and what is returned (UIDs and enriched metadata). It distinguishes from sibling tools like archive_emails or delete_emails.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies listing is for overview but does not explicitly state when to use it versus alternatives like search_emails or read_email. No exclusions or comparisons are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_foldersA

List all available IMAP folders/mailboxes in your Yahoo Mail account

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. While it correctly indicates a read-only list operation, it does not disclose any further behavioral traits like rate limits, authentication requirements, or the meaning of 'available'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no extraneous words, directly front-loading the core action and resource. Every word is necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the zero-parameter input and absence of an output schema, the description adequately covers the tool's purpose. However, it could provide more context about what 'available' entails (e.g., system folders vs. user-created) to be fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, and the schema coverage is 100% (empty). The description adds clear meaning by specifying the context and type of folders listed, which justifies a baseline score of 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List all available') and the resource ('IMAP folders/mailboxes') in the context of a Yahoo Mail account. It distinguishes itself from sibling email-related tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving available folders before performing email operations, but provides no explicit guidance on when to use this tool versus alternatives or any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mark_as_readA

Mark emails as read using UIDs. UIDs are permanent identifiers.

ParametersJSON Schema
NameRequiredDescriptionDefault
uidsYesArray of UIDs to mark as read
folderNoFolder containing emails (default: INBOX)INBOX

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavioral traits. It mentions UIDs are permanent, but does not explain side effects (e.g., idempotency, notification triggers) or error handling for invalid UIDs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no fluff, directly conveys purpose and a key behavioral note (UID permanence).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a simple action with two parameters, but lacks mention of edge cases or return behavior. Could benefit from a note on idempotency or error scenarios.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers 100% of parameters with descriptions, so baseline is 3. The description adds context about UIDs being 'permanent identifiers', enriching understanding of the parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Mark emails as read') and specifies the resource and method ('using UIDs'), distinguishing it clearly from sibling tools like 'archive_emails' or 'mark_as_unread'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives (e.g., marking as read vs. archiving), nor does it mention prerequisites or limitations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mark_as_unreadA

Mark emails as unread using UIDs. UIDs are permanent identifiers.

ParametersJSON Schema
NameRequiredDescriptionDefault
uidsYesArray of UIDs to mark as unread
folderNoFolder containing emails (default: INBOX)INBOX

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only mentions that UIDs are permanent identifiers, but fails to state whether the operation requires authentication, what happens if a UID is invalid, or if it is reversible.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no wasted words. Front-loaded with the main action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations and output schema, the description is too minimal. It does not explain return values, error behavior, or how to select this tool among 10 siblings. The email context is under-specified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that UIDs are permanent identifiers, which clarifies the parameter's stability beyond the schema's description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the action ('Mark emails as unread'), the resource ('emails'), and the method ('using UIDs'). It clearly distinguishes from sibling tools like mark_as_read.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies that UIDs are needed but does not explicitly specify when to use this tool versus alternatives (e.g., mark_as_read, flag_emails). No when-not or context provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

move_emailsA

Move emails to a specified folder using UIDs. UIDs are permanent identifiers. Use list_folders to see available folders.

ParametersJSON Schema
NameRequiredDescriptionDefault
uidsYesArray of UIDs to move
folderNameYesName of the destination folder (e.g., "Work", "Personal"). Use list_folders to see available folders.
sourceFolderNoSource folder containing the emails (default: INBOX)INBOX

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It explains the use of UIDs and hints at folder discovery via list_folders, but does not mention side effects like flag preservation, permissions, or rate limits, which limits transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences that contain no redundant information. It is front-loaded with the core action and adds a helpful pointer to list_folders, making it efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple move operation with no output schema, the description covers the essential: target folder and identifier usage. It could mention expected outcomes or errors, but given the straightforward nature, it is adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema: it reinforces using UIDs and suggests list_folders for folderName. No additional guidance on sourceFolder or parameter formatting is provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it moves emails to a specified folder using UIDs, and notes UIDs are permanent identifiers. It effectively distinguishes the action from siblings like archive or delete, although it could elaborate on the move semantics (e.g., source removal).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description suggests using list_folders to see available folders, providing useful context. However, it lacks explicit guidance on when to prefer move_emails over archive_emails or delete_emails, nor does it specify prerequisites or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_emailA

Read email content using UIDs (permanent identifiers). UIDs don't change when emails are deleted. Get UIDs from list_emails or search_emails.

ParametersJSON Schema
NameRequiredDescriptionDefault
uidsYesArray of UIDs to read. UIDs are permanent identifiers from list_emails.
folderNoFolder containing the emails (default: INBOX)INBOX

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits. It explains UID permanence and sources, but omits whether reading changes state (e.g., marks as read), response format, or potential side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences: first states purpose, second explains UID property, third directs to source tools. No redundant phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers input well but lacks output details (e.g., content format, fields). With no output schema, this gap is significant. Context among siblings is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the description adds only marginal context by reinforcing UID provenance. It does not provide additional semantic detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Read email content using UIDs' with specific verb and resource, and distinguishes from siblings by emphasizing the use of permanent identifiers. It also notes that UIDs come from list_emails or search_emails.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates when to use (to read email content) and provides prerequisites (get UIDs from other tools). However, it lacks explicit exclusions or alternative usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_emailsC

Search emails using UIDs with advanced filters. Returns UIDs which are permanent identifiers that don't change when emails are deleted. Get UIDs from results for subsequent operations.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNoSearch term for subject or sender (can be empty for date-only searches)
countNoNumber of results to return (default: 10, max: 50)
dateFromNoFilter emails from this date onwards (ISO 8601 or RFC 2822 format)
dateToNoFilter emails up to this date (ISO 8601 or RFC 2822 format)
senderNoFilter by specific sender email address or name
unreadOnlyNoOnly return unread emails (default: false)
folderNoFolder to search in (default: INBOX). Use list_folders to see available folders.INBOX

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must disclose behavior. It mentions UID permanence and usage for subsequent operations but omits whether it is read-only, rate limits, or authentication needs. Incomplete for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with purpose and key output detail (UID permanence). Efficient but could be slightly more structured for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given high schema coverage and no output schema, description covers purpose and UID output but lacks details on return format, pagination, and example usage. Adequate but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% parameter description coverage, so description adds limited parameter value. It reinforces 'advanced filters' but does not explain parameter interplay. Meets baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches emails with advanced filters and emphasizes UIDs as permanent identifiers. This distinguishes it from list_emails which may not use advanced filters, but no explicit sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like list_emails or other search methods. No mention of prerequisites or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

unflag_emailsB

Remove flag/star from emails using UIDs. UIDs are permanent identifiers.

ParametersJSON Schema
NameRequiredDescriptionDefault
uidsYesArray of UIDs to unflag
folderNoFolder containing emails (default: INBOX)INBOX

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, putting the full burden on the description. It only states that flags are removed and notes UIDs are permanent. It lacks details on side effects (e.g., whether other metadata changes), error handling for invalid UIDs, permissions required, or if the operation is reversible. Essential behavioral context is missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two short, direct sentences. The first states the action, the second adds a key detail about UIDs. No unnecessary words. It is efficiently structured and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 params, no nested objects, no output schema), the description is mostly adequate. However, it lacks completeness in terms of behavioral expectations and error scenarios. For instance, it does not clarify if the operation is idempotent or what happens if a UID doesn't exist. The lack of annotations further reduces completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with both parameters described sufficiently. The description adds the fact that UIDs are 'permanent identifiers', which is helpful context beyond the schema's 'Array of UIDs to unflag'. However, this is a minor addition, and the baseline of 3 is appropriate since the schema already explains the parameters well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Remove flag/star from emails using UIDs.' It identifies the resource (emails' flags/stars) and the method (using UIDs). This distinguishes it from sibling tools like 'flag_emails' which adds flags, and other tools with different actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when not to use it, or compare with other tools like 'mark_as_read' or 'delete_emails'. The agent must infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation5/5

Each tool has a distinctly separate purpose: archiving, deleting, flagging, listing, marking read/unread, moving, reading, searching, and unflagging. No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., archive_emails, delete_emails, list_folders). No mixing of conventions.

Tool Count5/5

11 tools is an appropriate number for an email management server, covering core operations without being overly numerous or sparse.

Completeness3/5

The tool set covers reading, searching, and organizing emails, but lacks tools for composing, sending, or drafting emails, which are significant missing operations for an email server.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Yahoo Mail MCP Server

    mayur200904
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables reading, searching, composing, and managing Yahoo Mail emails via IMAP with OAuth support for both local and remote MCP clients.
    48
    ISC

  • cpanel-mail-mcp

    rosauceda
    A
    license
    A
    quality
    B
    maintenance
    Manages email accounts via IMAP/SMTP, enabling reading, searching, sending, replying, forwarding, and folder management with multi-user and OAuth support.
    22
    MIT

  • Yahoo Mail MCP Server

    tomboone
    F
    license
    A
    quality
    B
    maintenance
    An MCP server that provides full email management for Yahoo Mail via IMAP, including tools to list, read, search, delete, archive, flag, and move emails, with secure OAuth authentication and support for local and remote deployments.
    11
    1

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jtokib/yahoo-mail-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server