MCP Aruba Email

🚀 MCP Aruba Email & Calendar Server

An MCP (Model Context Protocol) server for accessing Aruba emails and calendars via IMAP/SMTP/CalDAV. It easily integrates Aruba emails and calendars with AI assistants like Claude!

Italian | English

✨ Features

Email

• 📧 List emails - Navigate through the inbox with sender filters
• 🔍 Search emails - Search by subject/body with date filters
• 📖 Read emails - Get the full content
• ✉️ Send emails - Send emails via SMTP with a personalized signature
• ✍️ Email signature - Create professional signatures with photos and brand colors

Calendar

• 📅 Create events - Create calendar events with participants
• 📋 List events - View future events
• ✅ Accept invitations - Accept calendar invitations
• ❌ Decline invitations - Decline calendar invitations
• ❓ Maybe - Respond "maybe" to calendar invitations
• 🗑️ Delete events - Remove events from the calendar

General

• 🔒 Secure - Use IMAP/SMTP/CalDAV over SSL/TLS
• ⚡ Fast - Efficiently manage connections with a context manager
• 🤖 AI-ready - Works perfectly with Claude Desktop and other MCP clients

📦 Installation

# Clone the repository
git clone https://github.com/jackfioru92/mcp-aruba-email.git
cd mcp-aruba-email

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

📚 Configuration

1. Copy .env.example to .env:

cp .env.example .env

2. Edit .env with your Aruba credentials:

# Email configuration
IMAP_HOST=imaps.aruba.it
IMAP_PORT=993
IMAP_USERNAME=your_email@aruba.it
IMAP_PASSWORD=your_password

SMTP_HOST=smtps.aruba.it
SMTP_PORT=465

# Calendar configuration
CALDAV_URL=https://syncdav.aruba.it/calendars/your_email@aruba.it/
CALDAV_USERNAME=your_email@aruba.it
CALDAV_PASSWORD=your_password

3. (Optional) Configure your personalized email signature:

   Method 1: Interactive Script (Recommended)

   # Run the interactive script
   python setup_signature.py
   

   The script will guide you through creating a professional signature with:

   • 📝 Personal information (name, role, company, contacts)
   • 🎨 Style selection (professional, minimal, colorful)
   • 🌈 Color customization
   • 📸 Automatic photo upload to Imgur (optional)

   Method 2: Via Claude (Even easier!)

   After configuring Claude Desktop, simply ask:
   
   "Create an email signature for me with name Mario Rossi, 
    role Software Developer, company TechCorp and color #0066cc"
   
   "Configure my signature with this photo: /path/to/photo.jpg"
   
   "Set a minimal signature with just name and email"
   

   Claude will automatically use the MCP tools to create your signature!

The signature will be automatically included in all sent emails.

⚠️ Important Note

Credentials are stored locally and never leave your computer. The MCP server runs locally and connects directly to Aruba servers.

💻 Usage Examples

🚀 Quick Start: View the Latest Emails

The quickest way to get started:

# Install dependencies
pip install -e .

# Configure credentials (copy and edit .env.example)
cp .env.example .env
# Edit .env with your Aruba credentials

# Show the latest emails
python cli.py emails 5

# Or use the demo script
python demo_list_emails.py

Want to use Claude? After configuration, simply ask:

Show me the latest 5 emails
Give me the most recent emails
What emails did I receive today?

📖 Full Guide: See GUIDA_UTILIZZO_EMAIL.md for all available methods.

Run the server directly

python -m mcp_aruba.server

Configure with Claude Desktop

See CLAUDE_SETUP.md for detailed instructions.

Quick configuration for ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aruba-email-calendar": {
      "command": "python",
      "args": ["-m", "mcp_aruba.server"],
      "env": {
        "IMAP_HOST": "imaps.aruba.it",
        "IMAP_PORT": "993",
        "IMAP_USERNAME": "your_email@aruba.it",
        "IMAP_PASSWORD": "your_password",
        "SMTP_HOST": "smtps.aruba.it",
        "SMTP_PORT": "465",
        "CALDAV_URL": "https://syncdav.aruba.it/calendars/your_email@aruba.it/",
        "CALDAV_USERNAME": "your_email@aruba.it",
        "CALDAV_PASSWORD": "your_password"
      }
    }
  }
}

Configure with VS Code Copilot

See VSCODE_SETUP.md for detailed instructions on using this server with the VS Code Copilot MCP extension.

Use the quick CLI

# Activate the virtual environment
source .venv/bin/activate

# Show the latest 5 emails
python cli.py emails

# Show the latest 10 emails
python cli.py emails 10

# Show events in the next 7 days
python cli.py calendar

# Show events in the next 14 days
python cli.py calendar 14

🛠️ Available Tools

Email Tools

list_emails

List recent emails with optional filters.

Parameters:

• folder (str, default: "INBOX") - The email folder to read from
• sender_filter (str, optional) - Filter by sender email
• limit (int, default: 10, max: 50) - The number of emails to return

Examples:

Show the latest 5 emails from john@example.com
List recent emails in my inbox
Give me the 10 most recent emails from my boss

read_email

Read the full content of a specific email.

Parameters:

• email_id (str) - The email ID from list_emails
• folder (str, default: "INBOX") - The email folder

Examples:

Read email 123
Show me the full content of email 456

search_emails

Search for emails by subject or body content.

Parameters:

• query (str) - The search query
• folder (str, default: "INBOX") - The folder to search in
• from_date (str, optional) - Only emails from this date (format: DD-MMM-YYYY)
• limit (int, default: 10, max: 50) - The maximum number of results

Examples:

Search for emails about "API" from last week
Find all emails about "invoice" since December

send_email

Send an email via SMTP.

Parameters:

• to (str) - The recipient's email address
• subject (str) - The email subject
• body (str) - The email body (plain text)
• from_name (str, default: "Giacomo Fiorucci") - The sender's display name
• use_signature (bool, default: True) - Include the email signature if configured
• verify_recipient (bool, default: True) - Verify that the recipient's email exists

Examples:

Send an email to colleague@example.com thanking for the update
Reply to john@example.com with the project status

Note on signature: If you have configured a signature using setup_signature.py, it will be automatically included in emails. You can temporarily disable it with use_signature=False.

set_email_signature

Configure a personalized email signature.

Parameters:

• name (str) - Full name
• email (str) - Email address
• role (str, optional) - Role/position
• company (str, optional) - Company name
• phone (str, optional) - Phone number
• website (str, optional) - Website URL
• photo_input (str, optional) - Photo file path or URL (automatic upload to Imgur)
• style (str, default: "professional") - Style: professional, minimal, colorful
• color (str, default: "#0066cc") - Primary color (hexadecimal format)
• signature_name (str, default: "default") - Signature identifier name

Examples:

Create a signature with my name, role, and profile photo
Configure a professional signature with the company logo

get_email_signature

Get the current email signature.

Parameters:

• signature_name (str, default: "default") - The name of the signature to retrieve

list_email_signatures

List all saved email signatures.

Calendar Tools

create_calendar_event

Create a new calendar event.

Parameters:

• summary (str) - Event title
• start (str) - Start date/time in ISO format (YYYY-MM-DDTHH:MM:SS)
• end (str) - End date/time in ISO format
• description (str, optional) - Event description
• location (str, optional) - Event location
• attendees (str, optional) - Comma-separated list of attendee emails

Examples:

Create a meeting called "Team Meeting" tomorrow at 3 PM for 1 hour
Schedule a "Project Review" on December 10th at 2 PM with john@example.com

list_calendar_events

List calendar events within a date range.

Parameters:

• start_date (str, optional) - Start date in ISO format (default: today)
• end_date (str, optional) - End date in ISO format (default: 30 days from now)
• limit (int, default: 50) - Maximum number of events to return

Examples:

Show me my calendar for this week
What events do I have in December?
List all my meetings for the next 7 days

accept_calendar_event

Accept a calendar invitation.

Parameters:

• event_uid (str) - The event UID
• comment (str, optional) - Optional comment

Examples:

Accept the invitation to the meeting "Team Standup"
Accept the event abc123@aruba.it with the comment "Can't wait!"

decline_calendar_event

Decline a calendar invitation.

Parameters:

• event_uid (str) - The event UID
• comment (str, optional) - Optional comment

Examples:

Decline the event abc123@aruba.it
Decline the meeting with the comment "Sorry, I have a conflict"

tentative_calendar_event

Respond "maybe" to a calendar invitation.

Parameters:

• event_uid (str) - The event UID
• comment (str, optional) - Optional comment

Examples:

Respond maybe to the event abc123@aruba.it
Mark the meeting tomorrow as "maybe"
Maybe attend the meeting tomorrow

delete_calendar_event

Delete a calendar event.

Parameters:

• event_uid (str) - The UID of the event to delete

Examples:

Delete the event abc123@aruba.it
Cancel my meeting at 2 PM

📋 Use Cases

📬 Team Communication

Show me the latest emails from my team members
List unread emails from project@company.com

🔍 Project Tracking

Search for emails mentioning "API changes" from last week
Find all emails about "invoice" since December 1st

📊 Daily Email Summary

Summarize all the emails I received today
Show me the important emails from this morning

✉️ Quick Replies

Send an email to colleague@example.com thanking them for the update
Reply to john@example.com with the project status

📅 Calendar Management

What meetings do I have this week?
Create a team meeting for tomorrow at 3 PM
Accept the calendar invitation for Friday's review
Decline Monday's meeting, I'm on vacation
Show me my schedule for the next week

🤖 Email & Calendar Management with AI

With Claude Desktop or VS Code Copilot, you can:

• Ask Claude to summarize multiple emails
• Create responses based on email content
• Extract tasks from email threads
• Automatically organize and categorize emails
• Schedule meetings based on email conversations
• Manage calendar conflicts and find available time slots

🔧 Technical Details

• Python 3.10+ - Modern Python
• MCP SDK 1.2.0+ - Model Context Protocol for AI integration
• imaplib - Standard IMAP client library (SSL/TLS support)
• smtplib - Standard SMTP client library (SSL/TLS support)
• email - Email parsing and MIME handling
• caldav - CalDAV protocol for calendar access
• icalendar - iCalendar format parsing and generation
• python-dotenv - Environment variable management

🔒 Security & Privacy

• 🔒 Local execution - The server runs on your computer, and credentials never leave your machine
• 🛡️ SSL/TLS encryption - All connections use secure protocols (IMAPS port 993, SMTPS port 465, HTTPS for CalDAV)
• 🔐 Environment variables - Credentials are saved in the .env file (ignored by default in Git)
• 📝 Body truncation - Email body limited to 5000 characters to prevent context overflow
• ✅ No external services - Direct connection only to Aruba servers

Security Best Practices

1. Never commit the .env file to version control
2. Use strong and unique passwords for your email account
3. Consider enabling 2FA on your Aruba account
4. Regularly rotate your credentials
5. Review the MCP server logs for suspicious activity

⚙️ Performance

• ⚡ Connection pooling via context manager
• 📊 Configurable result limits to prevent memory issues
• 🚀 On-demand connections (no background process)
• 💾 Minimal memory footprint

🛠️ Development

Run the Tests

# Activate the virtual environment
source .venv/bin/activate

# Run email connection tests
python test_connection.py

# Run calendar connection tests
python test_calendar.py

# Test event creation
python test_create_event.py

# Test sending a calendar invitation
python send_invite.py

Code Quality

# Format the code
black src/

# Type checking
mypy src/

# Linting
pylint src/

📅 Enable CalDAV Synchronization

To use the calendar features, you need to enable CalDAV synchronization in Aruba Webmail:

1. Go to https://webmail.aruba.it
2. Navigate to the Calendar section
3. Click on "Synchronize calendar"
4. Select "Calendars" → "Proceed"
5. Choose "Read and write" (CalDAV) → "Proceed"
6. Select the calendars to synchronize → "Proceed"

Once enabled, you can fully manage your calendars via the MCP server!

🐞 Troubleshooting

Calendar not available

If you see "No calendar available", you need to enable CalDAV synchronization (see the section above).

Connection errors

1. Verify that the credentials in .env are correct
2. Check that ports 993 (IMAP), 465 (SMTP), 443 (CalDAV) are not blocked
3. Verify your firewall settings
4. Try running the test scripts

Emails or events not displayed

1. Verify that you have the correct permissions on your account
2. Check the applied filters (sender_filter, date filters)
3. Increase the result limit

❓ FAQ

Q: Is it safe to store my credentials in the .env file?
A: Yes, as long as the .env file is not committed to version control. It is already included in .gitignore. The credentials remain on your local computer.

Q: Can I use this with other email providers?
A: The server is optimized for Aruba, but you can adapt it for other providers that support IMAP/SMTP/CalDAV by modifying the configurations.

Q: How much do MCP servers cost?
A: MCP servers are free! This is open-source software. You only need a Claude or GitHub Copilot subscription to use it with those AI.

Q: Are my data sent to third parties?
A: No! The server runs locally and connects directly to Aruba servers. No data passes through third-party services.

Q: Can I contribute to the project?
A: Absolutely! See CONTRIBUTING.md for guidelines.

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CONTRIBUTING.md for full details.

🗺️ Roadmap

• [ ] Support for IMAP IDLE for real-time notifications
• [ ] Email attachment management
• [ ] HTML email composition
• [ ] pytest test suite
• [ ] Support for multiple accounts
• [ ] Recurring calendar events
• [ ] Calendar notifications
• [ ] Integration with other calendars (Google Calendar, Outlook)

📚 Documentation

• README.md - Main documentation (English)
• README_IT.md - Documentation in Italian
• GUIDA_UTILIZZO_EMAIL.md - Full Guide: How to View the Latest Emails 📧
• EXAMPLES.md - Usage examples
• CLAUDE_SETUP.md - Claude Desktop setup
• VSCODE_SETUP.md - VS Code Copilot setup
• CONTRIBUTING.md - Contribution guide
• LICENSE - MIT License

🆘 Support

If you encounter problems:

1. Check the Troubleshooting section
2. Run the test scripts to verify the connection
3. Check the logs for error messages
4. Open an issue on GitHub

📄 License

This project is released under the MIT License. See the LICENSE file for details.

👨‍💻 Author

Giacomo Fiorucci - giacomo.fiorucci@emotion-team.com

🙏 Acknowledgments

• Model Context Protocol for the MCP framework
• Anthropic for Claude Desktop
• GitHub for Copilot
• Aruba for reliable email and calendar services

⭐ If this project is useful to you, consider giving it a star on GitHub!