Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Meeting Scheduler MCPfind meeting requests from Lisa in my inbox"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 LTech 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
Find Requests: "Find meeting requests from Lisa"
Get Availability: "What times am I free this week?"
Suggest Times: "Suggest Thursday morning"
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 credentialsConfiguration
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 certificatesCalendar 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:8000API 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, body2. 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 timezone3. 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 pytestIntegration 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.pyTest Coverage
Run tests with coverage:
uv run pytest --cov=meeting_scheduler_mcp --cov-report=term-missingContributing
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.