Kolaborate-Platforms/kola-mail-mcp

Email Intelligence MCP Server

AI-powered email intelligence and analysis server for the Model Context Protocol (MCP). Provides Claude with tools to automatically analyze, categorize, prioritize, and extract actionable intelligence from your emails.

GitHub: Kolaborate-Platforms/kola-mail

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/Kolaborate-Platforms/kola-mail.git
cd kola-mail

# Install dependencies and build
bun install
bun run build

Configure Claude Desktop

Add to your Claude Desktop config file:

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

{
  "mcpServers": {
    "email-intelligence": {
      "command": "bun",
      "args": [
        "run",
        "/ABSOLUTE/PATH/TO/kola-mail/src/index.ts"
      ],
      "env": {
        "EMAIL_INTELLIGENCE_LOG_LEVEL": "info",
        "EMAIL_USER": "your-email@example.com",
        "EMAIL_PASSWORD": "your-password",
        "IMAP_HOST": "imap.example.com",
        "IMAP_PORT": "993",
        "IMAP_TLS": "true",
        "SMTP_HOST": "smtp.example.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "USE_DEMO_EMAILS": "false"
      }
    }
  }
}

Note: Replace /ABSOLUTE/PATH/TO/kola-mail with the actual path where you cloned the repository.

Restart Claude Desktop

IMPORTANT: Completely quit (Cmd+Q) and restart Claude Desktop for changes to take effect.

Test the Server

In Claude Desktop, say:

Test the email intelligence server

Expected response:

{
  "status": "ok",
  "message": "Email Intelligence MCP Server is running successfully!",
  "version": "1.0.0"
}

✨ Features

• 📧 Real Email Integration - Fetches emails via IMAP from your email server
• 🎯 Smart Categorization - 5 categories (urgent/important/routine/fyi/spam)
• ⚡ Priority Scoring - 0-10 intelligent priority based on 7+ factors
• ✅ Action Item Extraction - Automatically detects tasks and deadlines
• 😊 Sentiment Analysis - Positive, neutral, or negative classification
• 💬 Response Suggestions - AI-generated contextual replies
• 📤 Email Sending - Send emails via SMTP
• 🚀 Fast Caching - In-memory LRU cache with 5-minute TTL
• 🔒 Secure - SSL/TLS encryption, no permanent storage

🛠️ Available Tools

1. test_server

Health check to verify server is running.

Usage:

Test the email intelligence server

2. analyze_emails

Analyzes emails from your inbox with AI intelligence.

Parameters:

• emailSource: "inbox", "unread", "recent", or "custom"
• limit (optional): Max emails to analyze (default: 50, max: 200)
• since (optional): ISO date, only analyze emails after this date
• includeBody (optional): Include full body (default: false)
• filter (optional): Filter by from/subject/keywords

Usage Examples:

Analyze my unread emails

Analyze my emails from the last 7 days

Show me all urgent emails in my inbox

Returns:

{
  "emails": [
    {
      "id": "msg_123",
      "from": "ceo@company.com",
      "subject": "Urgent: Q4 Report Needed",
      "analysis": {
        "category": "urgent",
        "priority": 9.5,
        "sentiment": "neutral",
        "actionItems": [
          {
            "text": "Send the Q4 report",
            "priority": 9.5,
            "deadline": "2025-10-22T17:00:00Z"
          }
        ],
        "hasDeadline": true,
        "keyTopics": ["report", "deadline"],
        "reasoning": "Category: contains urgent keywords..."
      }
    }
  ],
  "summary": {
    "totalAnalyzed": 1,
    "urgentCount": 1,
    "actionItemCount": 1,
    "avgPriority": 9.5
  }
}

3. get_priority_emails

Returns priority-sorted emails with optional response suggestions.

Parameters:

• count (optional): Number of emails (default: 10, max: 50)
• minPriority (optional): Minimum priority 0-10 (default: 7)
• categories (optional): Filter by categories
• includeSuggestions (optional): Include AI response suggestions

Usage Examples:

Show me my top 5 most important emails

Get my urgent emails with response suggestions

4. send_email

Sends an email from your configured email account via SMTP.

Parameters:

• to: Recipient email(s)
• subject: Email subject
• body: Email body (plain text)
• html (optional): HTML body
• inReplyTo (optional): Message-ID for threading
• references (optional): Thread references

Usage Example:

Send an email to john@example.com saying:
Subject: Meeting Follow-up
Body: Thanks for the meeting today. I'll send the report by Friday.

🎯 Intelligence Engine

Category Classification

Priority Scoring (0-10)

Base Score: 5 (neutral)

Modifiers:

• Category: urgent +4, important +2, fyi -2, spam -5
• Action Items: +1.5 per item (max +6)
• Deadline Proximity:
  • Today: +3
  • 1-3 days: +2
  • 4-7 days: +1
• Sender Importance:
  • CEO/C-suite: +3
  • Manager: +2
  • Client: +2
  • VIP list: +1
• Email Age: >48h unread +2, >24h unread +1
• Keywords: "decision needed" +2, "please respond" +1

Priority Ranges:

• 9-10: 🔥 Drop everything, respond now
• 7-8: ⚡ High priority, respond today
• 5-6: 📌 Normal, respond within 2 days
• 3-4: 📋 Low priority, respond when convenient
• 0-2: 🗑️ Very low, may ignore

Action Item Detection

Automatically extracts action items using 20+ patterns:

• Direct requests: "please...", "could you...", "can you..."
• Formal requests: "kindly...", "request that you..."
• Explicit items: "action item:", "to-do:", "task:"
• Deadline-based: "by Friday...", "due...", "deadline..."

Sentiment Analysis

Keyword-based classification:

• Positive: thank, appreciate, excellent, great, success
• Negative: problem, issue, error, disappointed, failed
• Neutral: update, information, meeting, schedule

🔧 Configuration

Environment Variables

Set in .env file or Claude Desktop config:

# Email Account (Required for real emails)
EMAIL_USER=your-email@example.com
EMAIL_PASSWORD=your-password

# IMAP Configuration (Incoming)
IMAP_HOST=imap.example.com
IMAP_PORT=993
IMAP_TLS=true

# SMTP Configuration (Outgoing)
SMTP_HOST=smtp.example.com
SMTP_PORT=465
SMTP_SECURE=true

# Server Settings
EMAIL_INTELLIGENCE_LOG_LEVEL=info  # debug, info, warn, error
ANALYSIS_CACHE_TTL=300              # seconds (5 minutes)
ANALYSIS_MAX_EMAILS=200

# Mode
USE_DEMO_EMAILS=false               # true = demo data, false = real emails

Common Email Providers:

• Gmail: IMAP: imap.gmail.com:993, SMTP: smtp.gmail.com:465 (requires app password)
• Outlook/Office 365: IMAP: outlook.office365.com:993, SMTP: smtp.office365.com:587
• Custom/cPanel: Use your hosting provider's IMAP/SMTP settings

Customization

Edit src/config.ts to customize:

• Priority scoring weights
• Classification keywords
• VIP sender list
• Cache settings

📊 Architecture

src/
├── index.ts                    # MCP server entry point
├── types.ts                    # TypeScript type definitions
├── config.ts                   # Configuration and constants
├── email/
│   └── client.ts               # IMAP/SMTP email client
├── intelligence/
│   ├── analyzer.ts             # Main analysis orchestrator
│   ├── categorizer.ts          # Category classification
│   ├── prioritizer.ts          # Priority scoring
│   ├── action-extractor.ts     # Action item detection
│   ├── sentiment.ts            # Sentiment analysis
│   └── response-generator.ts   # Response suggestions
├── tools/
│   ├── test-server.ts          # Health check tool
│   ├── analyze-emails.ts       # Email analysis tool
│   ├── get-priorities.ts       # Priority emails tool
│   └── send-email.ts           # Email sending tool
└── utils/
    ├── cache.ts                # LRU cache with TTL
    └── logger.ts               # Logging utility

💻 Usage Examples

Example 1: Morning Email Triage

You: "Good morning! What are my most urgent emails?"

Claude:

1. Calls get_priority_emails(minPriority=8)
2. Fetches your real emails via IMAP
3. Returns: "You have 2 urgent emails:
   • CEO requesting Q4 report (Priority: 10/10)
   • Client bug report (Priority: 9/10)"

Example 2: Action Items

You: "What action items do I have from my emails?"

Claude:

1. Calls analyze_emails(emailSource="unread")
2. Extracts action items with deadlines
3. Returns organized list by priority

Example 3: Send Response

You: "Reply to that CEO email saying I'll have the report by EOD"

Claude:

1. Generates appropriate response
2. Calls send_email with professional reply
3. Sends via SMTP from your configured email account

🧪 Testing

Run Unit Tests

bun test

Type Check

bun run type-check

Manual Test

# Run server in dev mode
bun run dev

# In another terminal, you can test MCP protocol

🐛 Troubleshooting

Server Not Connecting

Symptoms: "No result received" or connection errors

Solutions:

1. Restart Claude Desktop - Must completely quit (Cmd+Q on macOS, or Exit on Windows/Linux) and reopen
2. Check logs:
   • macOS: ~/Library/Logs/Claude/mcp-server-email-intelligence.log
   • Windows: %APPDATA%\Claude\Logs\mcp-server-email-intelligence.log
   • Linux: ~/.config/Claude/logs/mcp-server-email-intelligence.log
3. Verify config path in claude_desktop_config.json
4. Check credentials in env variables

IMAP/SMTP Connection Errors

Check:

1. Credentials are correct in .env or config
2. IMAP/SMTP servers are reachable:

   telnet your-imap-host.com 993
   telnet your-smtp-host.com 465
   

3. For Gmail: Use an App Password instead of your regular password
4. Firewall allows connections

No Emails Found

Possible causes:

• Inbox is empty
• Filter criteria too restrictive
• Demo mode enabled (USE_DEMO_EMAILS=true)

Try:

Analyze all emails in my inbox (limit 10)

Demo Mode vs Real Mode

Real Mode (Production):

• Set USE_DEMO_EMAILS=false
• Fetches actual emails from IMAP
• Sends real emails via SMTP

Demo Mode (Testing):

• Set USE_DEMO_EMAILS=true
• Uses 6 built-in demo emails
• No real email connections

🔒 Security

• ✅ Credentials stored in environment variables (gitignored)
• ✅ SSL/TLS encryption for IMAP and SMTP
• ✅ No email content permanently stored
• ✅ Analysis cached temporarily (5-min TTL)
• ✅ Logs go to stderr (not interfering with MCP protocol)

📈 Performance

• Target: Analyze 50 emails in < 1 second
• Cache: LRU with 5-minute TTL
• Memory: < 100MB for 1000 emails
• Throughput: 1000+ emails/minute

🚀 Development

Project Setup

bun install
bun run build

Watch Mode

bun --watch run src/index.ts

Build

bun run build

📝 Resources

The server exposes these MCP resources:

• email://intelligence/rules - Current classification rules and keywords
• email://intelligence/stats - Cache statistics and performance metrics

🎉 What Makes This Special

Intelligent Analysis

• Goes beyond simple keyword matching
• Multi-factor priority scoring
• Context-aware categorization
• Deadline detection and tracking

Real Email Integration

• Direct IMAP/SMTP connection
• No third-party APIs needed
• Full control over your data
• Works with any email provider

Claude Integration

• Native MCP protocol
• Seamless conversation flow
• Natural language queries
• Contextual responses

📄 License

MIT

👨‍💻 Author

Calvin Magezi & Claude

Version: 1.0.0 Status: ✅ Production Ready License: MIT

🆘 Support

For issues or questions:

1. Check the troubleshooting section above
2. Review logs in your Claude logs directory (see troubleshooting section for paths)
3. Verify configuration in claude_desktop_config.json
4. Test with demo mode first: USE_DEMO_EMAILS=true
5. Open an issue on GitHub

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Last Updated: October 22, 2025