AGMail MCP Server

A lightweight server that provides email functionality for AI assistants through the Model Context Protocol (MCP).

Overview

This package allows AI assistants to send and receive emails using the AGMail service. It implements the Model Context Protocol (MCP), making it compatible with Claude Desktop and other AI platforms that support MCP.

Features

• Send Emails: Send emails to any recipient using your agent's email address
• Read Inbox: View all emails in your inbox
• Read Email: Read specific emails by ID
• Create Agent: Create new email agents
• Dynamic Email Addressing: Automatically uses the email address associated with your API key
• Simple Setup: One-command deployment with Claude Desktop

Dynamic Email Addressing

The AGMail MCP server features dynamic email addressing, which allows AI assistants to send emails using the email address associated with their API key. This eliminates the need to manually configure email addresses for each agent, making it easier to manage multiple agents and email accounts.

How It Works

1. API Key Mapping: Each API key is uniquely mapped to a specific user ID in the WildDuck email system
2. Automatic Email Retrieval: When sending emails, the system automatically retrieves the email address associated with your API key
3. Consistent Identity: All emails sent through the MCP will use your assigned email address, ensuring a consistent identity
4. No Configuration Required: You don't need to specify your email address in API calls - it's automatically handled

Benefits

• Simplified Integration: No need to hardcode email addresses in your code
• Improved Security: Your email address is never exposed in your code or configuration
• Consistent Experience: Users always receive emails from the same address
• Reduced Errors: Eliminates issues caused by misconfigured email addresses

When you create a new agent, the AGMail MCP server automatically assigns the email address associated with your API key to that agent. This email address is then used to send emails on behalf of the agent.

Prerequisites

1. AGMail Account: Register at agmail.ai to get your API key
2. Node.js: Version 14 or higher
3. Claude Desktop: Latest version of Claude Desktop

Technical Notes

MongoDB-Based Persistence (v1.0.60)

Version 1.0.60 introduces robust persistence mechanisms to ensure email mapping integrity:

• MongoDB Storage: All API key to WildDuck user mappings are stored in MongoDB
• Orphaned Email Recovery: Automatically recovers and routes emails after npm publishing or system restarts
• Process Restart Resilience: Mappings survive process restarts, npm publishing, and Docker container replacements
• Zero Downtime Migration: Seamlessly migrates existing mappings to the new storage system

Enhanced Email Integration (v1.0.10)

Version 1.0.10 introduces a robust email integration with the following features:

• Dynamic User Mapping: Intelligent mapping between API keys and WildDuck users
• Real Email Addresses: Uses actual email addresses from WildDuck users
• Consistent User Mapping: API keys consistently map to the same WildDuck user
• Fallback Mechanisms: Graceful handling when users can't be found
• Improved Logging: Detailed logging for better debugging

MongoDB Persistence (v1.0.59)

Version 1.0.59 introduces a MongoDB-based persistence mechanism for email synchronization:

• Persistent Mappings: API key to WildDuck user ID mappings now persist across process restarts and npm updates
• Cloud-Based Storage: Uses MongoDB for robust, cloud-native storage of mapping data
• Automatic Migration: Existing mappings are automatically migrated to the new storage system
• Zero Downtime: No disruption to existing users during the migration
• Improved Reliability: Prevents email loss or reset during system updates
• Compatibility Fix: Resolves an issue with stdout handling in Node.js environments
• Performance Optimization: Prevents hanging during email address lookup

Architecture

• API Key Architecture: User-facing API keys are UUID-style tokens (e.g., 44df55ba-868a-464a-aca5-10a80ba915ab)
• WildDuck Integration: Uses a single WildDuck master API token for all WildDuck API calls
• 1:1 Mapping: Each AGMail API key maps to a specific WildDuck user ID
• Simplified Authentication: Secure API key management
• User Mapping Service: Efficient user account management
• Comprehensive Tool Support: Full support for send_email, get_inbox, read_email, and create_agent

Direct Adapter Approach

The package now uses a direct adapter approach to communicate with the email backend, similar to the Python implementation. This ensures consistent behavior across different MCP server implementations.

MCP Protocol Support

Version 0.7.3 adds support for additional Model Context Protocol (MCP) methods required by Claude Desktop:

• resources/list: Returns available resources
• tools/list: Returns available tools
• prompts/list: Returns available prompts
• Support for notifications/initialized format

Health Check Improvements

Version 0.7.4 includes an improved health check mechanism that verifies connectivity to API endpoints without requiring specific health check endpoints. This makes the package more robust when connecting to different API server implementations.

If you're concerned about security implications, you can review the source code to see exactly how this is implemented. The package uses NODE_TLS_REJECT_UNAUTHORIZED='0' to bypass certificate validation.

Installation

For Claude Desktop Users

The simplest way to use AGMail with Claude Desktop is to add it to your Claude Desktop configuration file. No manual installation required!

1. Open your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the AGMail MCP server configuration:

{
  "mcpServers": {
    "agmail": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]"
      ],
      "env": {
        "AGMAIL_API_KEY": "your-api-key-here",
        "AGMAIL_API_BASE": "https://api.agmail.ai"
      }
    }
  }
}

3. Replace your-api-key-here with your actual AGMail API key
4. Save the file and restart Claude Desktop

Manual Installation

If you prefer to install the package globally:

npm install -g agmail

Then run it with:

AGMAIL_API_KEY=your-api-key-here agmail-mcp

Important: Replace your-api-key-here with your actual AGMail API key from agmail.ai.

Environment Variables

• AGMAIL_API_KEY (required): Your AGMail API key
• AGMAIL_API_BASE (optional): AGMail API base URL (defaults to https://api.agmail.ai)
• NODE_TLS_REJECT_UNAUTHORIZED (optional): Set to '0' to bypass SSL verification for development

Available Tools

This MCP server provides the following tools to Claude:

1. send_email

Send an email to a recipient.

Parameters:

• to: Email address of the recipient
• subject: Subject line of the email
• body: Body content of the email

Example:

Can you send an email to [email protected] with the subject "Meeting Tomorrow" and a brief message about our 2pm meeting?

2. get_inbox

Retrieve a list of emails in your inbox.

Parameters: None

Example:

Show me my recent emails

3. read_email

Read a specific email by its ID.

Parameters:

• id: ID of the email to read

Example:

Can you read the email with ID 12345?

Troubleshooting

• Connection Issues: Ensure your API key is correct and that you have an active internet connection
• Claude Not Recognizing Tools: Restart Claude Desktop after configuring the MCP server
• Permission Errors: Make sure you have the necessary permissions to execute the npx command

Support

For support, visit agmail.ai/support or email [email protected]

Features

• Send Emails: Allow AI assistants to send emails
• Read Inbox: Access and read incoming emails
• Create Agents: Create new email agents with unique addresses
• Secure Authentication: Uses API key authentication

MCP Protocol Implementation

This package implements the following MCP tools:

send_email

{
  "tool": "send_email",
  "params": {
    "to": "[email protected]",
    "subject": "Email Subject",
    "body": "Email content"
  }
}

get_inbox

{
  "tool": "get_inbox",
  "params": {
    "limit": 10,
    "page": 1
  }
}

read_email

{
  "tool": "read_email",
  "params": {
    "email_id": "email-id-here"
  }
}

create_agent

{
  "tool": "create_agent",
  "params": {
    "username": "agent-name",
    "name": "Agent Full Name",
    "description": "Agent description"
  }
}

Troubleshooting

Common Issues

• Authentication Failed: Verify your API key is correct
• Account Not Verified: Check your email for the verification link
• Quota Exceeded: Upgrade your plan for higher limits

Support

For support, please contact [email protected] or visit our documentation.

License

MIT