Meeting Scheduler MCP

Natural Language Meeting Scheduling with Personal Touch

The Problem with Scheduling Tools

Traditional scheduling tools like Calendly and Cal.com feel transactional for important contacts:

• Impersonal: Automated links lack human touch
• Manual Hell: Calendar tab-switching between email and scheduling apps
• Context Loss: No integration with email conversations

Our Goal: Natural language scheduling that feels personal and integrates seamlessly with your email workflow.

What We're Building

A Mistral Le Chat powered meeting scheduler that combines:

• Email Search: Find meeting requests in your inbox
• Calendar Management: YAML-based scheduling with holidays support
• Natural Language Interface: Chat-based scheduling workflow
• Email Threading: Maintain conversation context with proper email headers

Architecture Overview

sequenceDiagram
    participant U as User
    participant L as Mistral Le Chat
    participant M as MCP Server
    participant I as IMAP Server
    participant Y as calendar.yaml

    U->>L: "Find a meeting request from Lisa"
    activate L
    L->>M: search_emails(query="Lisa")
    activate M
    M->>I: IMAP SEARCH
    activate I
    I-->>M: Email results
    deactivate I
    M-->>L: Email
    deactivate M
    L->>M: get_free_slots()
    activate M
    M->>Y: Read free slots
    activate Y
    Y-->>M: Available times
    deactivate Y
    M-->>L: Free slots
    deactivate M
    L-->>U: "Lisa wants to meet. You're free Tue 2pm or Thu 10am"
    U->>L: "Suggest Thursday, keep it casual"
    L-->>U: Draft preview
    U->>L: "Send it"
    L->>M: save_draft_and_block_slot(...)
    activate M
    M->>Y: Write blocked slot
    M->>I: IMAP APPEND to INBOX.Drafts
    M-->>L: Confirmation
    deactivate M
    L-->>U: "Draft saved, slot blocked"
    deactivate L

Tech Stack

• Backend: Python 3.13+ with FastMCP
• Email Integration: IMAP with TLS/SSL support
• Calendar Storage: YAML file-based system
• Transport: HTTP/SSE for Mistral connector
• Data Models: Pydantic v2 for validation

Features

1. Email Integration

• IMAP Search: Find emails by criteria (sender, subject, etc.)
• Email Threading: Maintain conversation context with Message-ID, In-Reply-To, References
• Draft Management: Save email drafts with proper threading headers
• TLS/SSL Support: Secure connections with configurable SSL options

2. Calendar Management

• YAML Configuration: Simple, human-readable calendar format
• Weekly Availability: Define working hours and available slots
• Holiday Support: Automatic holiday detection (country-specific)
• Time Zone Awareness: Full timezone support with ZoneInfo
• Slot Finding: Intelligent free slot detection

3. Natural Language Workflow

1. Find Requests: "Find meeting requests from Lisa"
2. Get Availability: "What times am I free this week?"
3. Suggest Times: "Suggest Thursday morning"
4. Confirm & Block: "Confirm the meeting and block the slot"

Getting Started

Prerequisites

• Python 3.13+
• IMAP-enabled email account
• Mistral Le Chat integration

Installation

# Clone the repository
uv add git+https://github.com/seb-schulz/meeting-scheduler-mcp.git

# Install dependencies
uv sync

# Set up environment variables
cp .env.example .env
# Edit .env with your IMAP credentials

Configuration

Create a .env file with your IMAP settings:

# Required settings
IMAP_HOST=imap.example.com      # IMAP server hostname
IMAP_USER=your@email.com        # IMAP username/email
IMAP_PASSWORD=secure_password   # IMAP password
IMAP_FROM=your@email.com        # From address for sent emails

# TLS/SSL Configuration (optional with sensible defaults)
IMAP_PORT=993                  # IMAP port
IMAP_USE_SSL=true              # Use SSL/TLS
IMAP_USE_STARTTLS=false        # Use STARTTLS
IMAP_VERIFY_SSL=true           # Verify SSL certificates

Calendar Configuration

Edit calendar.yaml to define your availability:

schedule:
  timezone: Europe/Berlin
  slot_duration: 30
  holidays: DE
  weekly:
    - days:
        - mon
        - tue
        - wed
        - thu
        - fri
      slots:
        - start: 09:00:00
          end: "12:00:00"
        - start: "13:00:00"
          end: "17:00:00"
blocked: []

Running the Server

# Start the FastMCP server with Python module syntax
uv run python -m meeting_scheduler_mcp

# Server will be available at http://0.0.0.0:8000

API Tools

1. search_emails

Search emails with full metadata and threading support:

emails = search_emails(
    mailbox="INBOX",
    criteria="FROM lisa@example.com"
)
# Returns: List of emails with id, subject, from, to, date, message_id, in_reply_to, references, body

2. get_free_slots

Get available time slots from your calendar:

free_slots = get_free_slots()
# Returns: List of up to 50 available slots with date, start, end times, and timezone

3. save_draft_and_block_slot

Complete workflow: block calendar slot and save confirmation email draft:

result = save_draft_and_block_slot(
    datetime="2025-12-15T14:00:00+01:00",
    duration=30,
    reason="Meeting with Lisa",
    subject="Meeting Confirmed",
    body="Let's meet on Thursday at 2pm",
    to="lisa@example.com",
    in_reply_to="<original-message-id@example.com>"
)
# Returns: {"success": true} or {"error": "message", "success": false}

Testing

Unit Tests

Run tests with:

uv run pytest

Integration Tests with Docker Compose

For IMAP integration testing, use Docker Compose with Greenmail:

# Start Greenmail IMAP server
cd .devcontainer
docker-compose up -d greenmail

# Seed test emails
uv run python scripts/seed_test_emails.py

# Run tests with test configuration
IMAP_CONFIG=.env.test uv run pytest tests/test_integration.py

Test Coverage

Run tests with coverage:

uv run pytest --cov=meeting_scheduler_mcp --cov-report=term-missing

Contributing

Contributions welcome! Please follow:

• Code Style: Ruff linting rules
• Type Safety: Full Pydantic v2 typing
• Testing: Comprehensive pytest coverage
• Documentation: Keep README updated

License

MIT License - See LICENSE for details.

Learn More

• FastMCP Documentation
• Pydantic v2
• IMAP Protocol