proton-calendar-mcp

Hattmakaren/proton-calendar-mcp

3.2

If you are the rightful owner of proton-calendar-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Proton Calendar MCP Server provides read-only access to Proton Calendar data for AI assistants.

Tools
3
Resources
0
Prompts
0

Proton Calendar MCP Server

An MCP (Model Context Protocol) server that provides read-only access to your Proton Calendar data and optionally integrates with Trello for task management, all accessible through AI assistants like Claude Code.

Features

Calendar Features

  • Read-only access to your Proton Calendar via shareable URL
  • Three calendar tools for querying events:
    • get_today_events: Get all events scheduled for today
    • get_week_events: Get all events for the next 7 days
    • get_date_range_events: Get events for a custom date range

Trello Integration (Optional)

  • Read-only access to your Trello boards and cards
  • Four Trello tools for task management:
    • get_trello_cards_today: Get all cards due today
    • get_trello_cards_tomorrow: Get all cards due tomorrow
    • get_trello_overdue_cards: Get overdue cards with day count
    • get_trello_cards_date_range: Get cards due within a date range
  • Rich card details: Labels, checklists, descriptions, board/list info
  • Automatic board filtering via environment variable

Planning Agents

  • Daily summary agent with intelligent preparation suggestions for today and tomorrow
  • Weekly planner agent with monthly overview and intelligent task suggestions
  • Both agents include workload analysis and smart planning tips

Prerequisites

  • Python 3.8 or higher (tested with Python 3.13)
  • A Proton Calendar account
  • A shareable calendar URL from Proton Calendar (read-only)
  • (Optional) A Trello account with API key and token for Trello integration

Setup Instructions

1. Get Your Proton Calendar Share URL

  1. Go to calendar.proton.me
  2. Select the calendar you want to share
  3. Click on the calendar settings (three dots menu)
  4. Select "Share" or "Get shareable link"
  5. Generate a read-only URL for your calendar
  6. Copy the URL (it should be in .ics format)

2. Install Dependencies

cd proton-calendar-mcp
pip install -r requirements.txt

3. Configure Environment Variables

All configuration is managed through a centralized .env file in the proton-calendar-mcp directory.

Create the .env file

Create a file named .env in the proton-calendar-mcp directory with the following content:

# Proton Calendar Configuration (Required)
PROTON_CALENDAR_URL=https://calendar.proton.me/api/calendar/v1/url/YOUR_CALENDAR_ID/calendar.ics

# Trello Configuration (Optional - for task integration)
TRELLO_API_KEY=your_trello_api_key_here
TRELLO_TOKEN=your_trello_token_here

# Optional: Comma-separated list of board IDs to monitor (leave empty for all boards)
TRELLO_BOARD_IDS=
Get your Trello credentials (Optional)

To enable Trello integration:

  1. Get your Trello API Key:

  2. Generate a Trello Token:

    • Visit: https://trello.com/1/authorize?expiration=never&name=ProtonCalendarMCP&scope=read&response_type=token&key=YOUR_API_KEY
    • Replace YOUR_API_KEY with your actual API key
    • Click "Allow" to generate your token

  3. Add credentials to .env file:

    • Update TRELLO_API_KEY with your API key
    • Update TRELLO_TOKEN with your token
    • Optionally set TRELLO_BOARD_IDS to specific board IDs (comma-separated)

Note:

  • The .env file is gitignored for security
  • If TRELLO_BOARD_IDS is not set, the server will fetch cards from all your boards
  • All scripts (MCP server, daily_summary, trello_client) use this centralized configuration

4. Register with Claude Code

Register the MCP server with Claude Code using stdio transport. Since all configuration is in the .env file, the registration is simple:

claude mcp add --transport stdio proton-calendar -- python /path/to/proton-calendar-mcp/server.py

Example for Windows:

claude mcp add --transport stdio proton-calendar -- python C:\Users\YourName\proton-calendar-mcp\server.py

Example for Linux/Mac:

claude mcp add --transport stdio proton-calendar -- python /home/yourname/proton-calendar-mcp/server.py

Important:

  • Update the path to match where you saved the project
  • The server will automatically load configuration from the .env file
  • No need to pass environment variables via --env flags

5. Verify Installation

Check that the server is registered and connected:

claude mcp list

You should see:

proton-calendar: python /path/to/server.py - ✓ Connected

Usage

Using with Claude Code

Once configured, you can ask Claude Code questions about both your calendar and Trello boards:

Calendar queries:

  • "What's on my calendar today?"
  • "Show me my schedule for the next week"
  • "What events do I have between January 15 and January 20?"

Trello queries (if configured):

  • "What Trello cards are due today?"
  • "Show me my overdue Trello tasks"
  • "What cards do I have due tomorrow?"
  • "Show me Trello cards due this week"

Combined queries:

  • "What do I have on my schedule today, including Trello tasks?"
  • "Show me everything due tomorrow - calendar and Trello"

Claude Code will automatically use the appropriate tools to fetch and display your data.

Daily Summary Agent

The project includes a daily summary agent that provides an intelligent overview combining both calendar events and Trello tasks:

cd proton-calendar-mcp
python daily_summary.py

Features:

  • ⚠️ Shows overdue Trello tasks (with days overdue)
  • 📅 Shows today's complete schedule (calendar + Trello tasks)
  • 🔮 Previews tomorrow's events and tasks
  • 🎯 Suggests preparation needed for tomorrow's meetings
  • 💡 Provides helpful tips (early morning alerts, back-to-back meeting warnings)
  • ⏰ Highlights important scheduling considerations

Note: The daily summary automatically loads configuration from the .env file, including Trello integration if configured.

Example output:

============================================================
📅 DAILY SUMMARY
🗓️  Friday, November 14, 2025
============================================================

⚠️  OVERDUE TASKS
------------------------------------------------------------
• Ring om Gästhuset hyresgäst
  📋 Quest log → Weekly commitment
  ⏰ Due: 2025-11-07 01:03 PM (7 days overdue)
  🔗 https://trello.com/c/UYSzpJhy/...

📊 You have 1 overdue task(s) - prioritize these!

============================================================

🌟 TODAY'S SCHEDULE
------------------------------------------------------------
• Team Meeting
  ⏰ 02:00 PM - 03:00 PM
  📍 Conference Room A
  📝 Weekly sync meeting

📊 You have 1 event(s) scheduled today

------------------------------------------------------------
📝 TODAY'S TASKS (Trello)
------------------------------------------------------------
• Review pull request
  📋 Quest log → Weekly commitment
  ⏰ Due: 04:00 PM
  🏷️  Development
  🔗 https://trello.com/c/abc123/...

📊 You have 1 task(s) due today

============================================================
🔮 PREPARE FOR TOMORROW
📆 Saturday, November 15, 2025
------------------------------------------------------------
• Product Demo
  ⏰ 10:00 AM - 11:00 AM
  📍 Main Office
  📝 Demo new features to stakeholders
  🎯 Preparation needed:
     - Prepare slides and test equipment
     - Practice presentation
     - Review agenda and prepare talking points

📊 You have 1 event(s) tomorrow

============================================================
💡 TIPS
------------------------------------------------------------
🚨 You have overdue tasks - prioritize completing these first!
📋 Review tomorrow's schedule tonight
💧 Stay hydrated and take breaks!
============================================================

Intelligent preparation suggestions:

The agent analyzes your events and provides context-aware preparation suggestions:

  • Meetings → Review agenda and prepare talking points
  • Presentations → Prepare slides, test equipment, practice
  • Interviews → Review resumes, prepare questions
  • Training → Review materials, prepare questions
  • Travel required → Check directions, book rooms

Automation tip: You can schedule this to run automatically:

  • Windows: Use Task Scheduler
  • Linux/Mac: Use cron job

Example cron entry (run daily at 7 AM):

0 7 * * * cd /path/to/proton-calendar-mcp && python daily_summary.py

Weekly Planner Agent

The project includes a weekly planner agent that analyzes the next month and suggests tasks for the upcoming week:

cd proton-calendar-mcp
python weekly_planner.py

Features:

  • 📅 Monthly overview with 4 weeks of upcoming events and deadlines grouped by week
  • ⚠️ Overdue tasks highlighted with urgent attention needed
  • 📆 This week's complete schedule with preparation suggestions
  • ✅ Intelligent task suggestions based on:
    • Due dates and priorities
    • Available time between calendar events
    • Workload balance across the week
  • 💡 Planning tips with workload assessment (busy/moderate/light week)
  • 🎯 Preparation suggestions for important events (meetings, presentations, etc.)

Note: The weekly planner automatically loads configuration from the .env file, including Trello integration if configured.

Output Sections:

  1. Monthly Overview (4 weeks):

    • Events and tasks grouped by week
    • Quick counts and highlights
    • Helps identify busy vs. light weeks ahead

  2. This Week's Focus:

    • Overdue tasks requiring urgent attention
    • Complete schedule with event details
    • Preparation suggestions for meetings/presentations
    • Intelligently suggested tasks with priority levels (🔴 urgent, 🟠 high, 🟡 medium, 🟢 normal)

  3. Planning Tips:

    • Workload assessment for the week
    • Free days available for focused work
    • Reminders to review and update tasks

Automation tip: Schedule this to run weekly (e.g., Sunday evening or Monday morning):

# Run weekly on Sunday at 8 PM
0 20 * * 0 cd /path/to/proton-calendar-mcp && python weekly_planner.py

Available Tools

Calendar Tools

get_today_events

Returns all events scheduled for today.

No parameters required

Example output:

Events for Today:

• Test Meeting
  Time: 02:00 PM
  Location: Conference Room A
  Description: This is a test meeting

• Team Standup
  Time: 10:00 AM
  Location: Office
get_week_events

Returns all events scheduled for the next 7 days, grouped by date.

No parameters required

Example output:

Events for the Next Week:

Wednesday, November 13, 2025:
  • Test Meeting (02:00 PM)
    Location: Conference Room A

Thursday, November 14, 2025:
  • Team Standup (10:00 AM)
    Location: Office
get_date_range_events

Returns events within a specified date range.

Parameters:

  • start_date (string): Start date in YYYY-MM-DD format
  • end_date (string): End date in YYYY-MM-DD format

Example output:

Events from 2025-11-13 to 2025-11-20:

Wednesday, November 13, 2025:
  • Test Meeting (02:00 PM)
    Location: Conference Room A
    Description: This is a test meeting

Trello Tools

Note: Trello tools are only available if Trello credentials are configured.

get_trello_cards_today

Returns all Trello cards due today.

No parameters required

Example output:

Trello Cards Due Today:

• Fix authentication bug
  Board: Development → In Progress
  Due: 02:00 PM
  Labels: High Priority, Bug
  Checklist: 2/5 completed
  URL: https://trello.com/c/abc123

• Review pull request
  Board: Development → Review
  Due: 04:00 PM
  Labels: Review
  URL: https://trello.com/c/def456
get_trello_cards_tomorrow

Returns all Trello cards due tomorrow.

No parameters required

Output format: Same as get_trello_cards_today

get_trello_overdue_cards

Returns all overdue Trello cards with days overdue count.

No parameters required

Example output:

Overdue Trello Cards (3 total):

• Update documentation
  Board: Documentation → To Do
  Due: 2025-11-10 09:00 AM (3 days overdue)
  Labels: Documentation
  Checklist: 0/3 completed
  URL: https://trello.com/c/ghi789
get_trello_cards_date_range

Returns Trello cards due within a specified date range.

Parameters:

  • start_date (string): Start date in YYYY-MM-DD format
  • end_date (string): End date in YYYY-MM-DD format

Example output:

Trello Cards Due 2025-11-13 to 2025-11-20:

Wednesday, November 13, 2025:
  • Deploy to production
    Board: Operations → Scheduled
    Due: 02:00 PM
    Labels: Deploy, Critical
    Checklist: 5/7 completed
    URL: https://trello.com/c/jkl012

Thursday, November 14, 2025:
  • Team retrospective
    Board: Team → Meetings
    Due: 10:00 AM
    URL: https://trello.com/c/mno345

Testing

Run the test suite to verify all functionality:

cd proton-calendar-mcp
pytest tests/ -v

All tests should pass:

37 passed in 2.5s

Test Coverage

The test suite includes:

Calendar Fetching Tests (11 tests):

  • ✅ Successful calendar fetching
  • ✅ HTTP error handling
  • ✅ Invalid data handling
  • ✅ Timeout handling
  • ✅ Event formatting
  • ✅ Date range filtering
  • ✅ Today's events filtering
  • ✅ Event sorting
  • ✅ All-day event handling

Daily Summary Agent Tests (12 tests):

  • ✅ Preparation analysis for meetings
  • ✅ Preparation analysis for presentations
  • ✅ Preparation analysis for interviews
  • ✅ Location-based preparation
  • ✅ Training event preparation
  • ✅ Time formatting
  • ✅ Event summary formatting
  • ✅ Long description handling
  • ✅ Multiline description handling

Trello Client Tests (14 tests):

  • ✅ Client initialization and credentials
  • ✅ Card formatting with all attributes
  • ✅ Checklist progress tracking
  • ✅ Label and attachment handling
  • ✅ Date filtering (today, tomorrow, overdue)
  • ✅ Date range filtering
  • ✅ Card sorting by due date
  • ✅ Edge cases (no due date, timezone handling)

Architecture

Components

MCP Server (server.py):

  1. fetch_calendar(): Async function to fetch and parse iCalendar data from URL
  2. format_event(): Extracts relevant information from calendar events
  3. filter_events_by_date_range(): Filters and sorts events by date
  4. Trello Integration: Optional Trello client for task management
  5. MCP Server: Exposes 3 calendar tools + 4 Trello tools (if configured) via MCP

Trello Client (trello_client.py):

  1. TrelloCardFetcher: Main client class for Trello API interaction
  2. get_cards_from_boards(): Fetches cards from specified boards
  3. filter_cards_by_due_date(): Filters and sorts cards by due date
  4. get_cards_due_today/tomorrow(): Convenience methods for common queries
  5. get_overdue_cards(): Identifies and returns past-due cards
  6. _format_card(): Extracts comprehensive card details (labels, checklists, etc.)

Daily Summary Agent (daily_summary.py):

  1. generate_daily_summary(): Creates comprehensive daily overview
  2. analyze_preparation_needs(): Intelligent preparation suggestions
  3. format_event_summary(): User-friendly event formatting
  4. Smart tips: Early morning alerts, back-to-back meeting warnings

Weekly Planner Agent (weekly_planner.py):

  1. generate_weekly_planner(): Creates comprehensive weekly/monthly overview
  2. calculate_weekly_workload(): Analyzes calendar density and free time
  3. suggest_weekly_tasks(): Intelligent task selection based on priorities and workload
  4. group_by_week(): Groups events and tasks into weekly buckets
  5. format_monthly_overview(): Creates 4-week lookahead summary
  6. Planning intelligence: Workload assessment and task distribution recommendations

Dependencies

  • mcp>=1.0.0 - Official Model Context Protocol SDK
  • icalendar>=6.0.0 - RFC 5545 compliant iCalendar parser
  • httpx>=0.27.0 - Modern async HTTP client
  • py-trello>=0.19.0 - Trello API client library
  • python-dotenv>=1.0.0 - Environment variable management from .env files
  • pytest>=8.0.0 - Testing framework
  • pytest-asyncio>=0.23.0 - Async support for pytest

Security & Privacy

  • This server only has read-only access to your calendar and Trello boards
  • Your calendar URL and Trello credentials should be kept private
  • The MCP server runs locally on your machine
  • No data is sent to third-party services except:
    • Proton's servers to fetch your calendar
    • Trello's API to fetch your cards (if configured)
  • All credentials are passed via environment variables for security
  • Trello integration is optional - works fine without it

Troubleshooting

Calendar Issues

"PROTON_CALENDAR_URL environment variable is not set"

  • Make sure you've created the .env file in the proton-calendar-mcp directory
  • Verify the .env file contains the PROTON_CALENDAR_URL setting
  • Check that the .env file is in the same directory as server.py

"Error fetching calendar: [HTTP error]"

  • Verify your calendar URL is correct
  • Check that the URL is publicly accessible (test it in a browser)
  • Ensure you have internet connectivity
  • Make sure the calendar URL hasn't expired

Events not showing up

  • Verify events exist in your Proton Calendar for the queried date range
  • Check that the events are in the calendar you shared (not a different calendar)
  • Ensure the shareable link is still active

Trello Issues

Trello tools not appearing

  • Verify TRELLO_API_KEY and TRELLO_TOKEN are set in your .env file
  • Check that the credentials are correct
  • Restart the MCP server: claude mcp remove proton-calendar -s local then re-add it

"Error: Trello is not configured"

  • This means the Trello credentials are missing or invalid in the .env file
  • Double-check your API key and token in .env
  • Ensure the .env file is in the correct location (proton-calendar-mcp directory)

No cards returned from Trello

  • Verify you have cards with due dates in your boards
  • Check that TRELLO_BOARD_IDS (if set) contains valid board IDs
  • Ensure your API token has read access to the boards

How to find Trello Board IDs:

  1. Open your Trello board in a browser
  2. Add .json to the end of the URL: https://trello.com/b/BOARD_ID/board-name.json
  3. Look for the id field in the JSON response
  4. Use this ID in the TRELLO_BOARD_IDS environment variable

General Issues

Tests failing If tests fail:

  1. Ensure all dependencies are installed: pip install -r requirements.txt
  2. Check Python version: python --version (should be 3.8+)
  3. Run tests with verbose output: pytest tests/ -v -s

Server not responding

  • Check that the server process is running
  • Verify Claude Code is properly connected: claude mcp list
  • Look for error messages in the server logs

Development

To test the server manually:

python server.py

The server will start and wait for MCP protocol messages on stdin.

Project Structure

proton-calendar-mcp/
├── server.py                          # Main MCP server implementation
├── trello_client.py                   # Trello API client module
├── daily_summary.py                   # Daily summary agent with intelligent prep suggestions
├── weekly_planner.py                  # Weekly planner agent with monthly overview
├── requirements.txt                   # Python dependencies
├── pytest.ini                         # Pytest configuration
├── .env                               # Centralized configuration file (create this, gitignored)
├── .env.example                       # Example configuration template
├── .gitignore                         # Git ignore rules
├── README.md                          # This file
└── tests/
    ├── test_calendar_fetch.py         # Calendar MCP server test suite
    ├── test_daily_summary.py          # Daily summary agent test suite
    ├── test_trello_client.py          # Trello client test suite
    └── test_server_trello_integration.py  # Trello MCP integration tests

Limitations

Calendar Limitations

  • Read-only: This server can only read calendar data, not create or modify events
  • No CalDAV: Proton Calendar doesn't support CalDAV, so we use shareable URLs
  • No API: Proton doesn't provide a public API, so this relies on .ics export
  • Single calendar: Each server instance can only access one shared calendar

Trello Limitations

  • Read-only: This server can only read Trello cards, not create or modify them
  • Due dates only: Only cards with due dates are returned by the filtering functions
  • No webhooks: The server polls Trello on each request (no real-time updates)
  • Rate limits: Trello API has rate limits (300 requests per 10 seconds per token)

Future Enhancements

Potential improvements:

  • Support for multiple Proton calendars
  • Caching to reduce API calls for both services
  • Event/card search by keywords
  • Support for recurring events
  • Write capabilities for Trello (create/update cards)
  • Trello card comments and activity
  • Export data to different formats
  • Integration with other task management systems

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Credits

Built with: