calendar-mcp

Google Calendar MCP Server (Python)

This project implements a Python-based MCP (Model Context Protocol) server that acts as an interface between Large Language Models (LLMs) and the Google Calendar API. It enables LLMs to perform calendar operations via natural language requests.

Features

• Authentication: Secure Google Calendar API access using OAuth 2.0 (Desktop App Flow with automatic token storage/refresh).
• Core Calendar Actions:
  • List calendars (mcp_google_calendar_list_calendars).
  • Create calendars (mcp_google_calendar_create_calendar).
  • Find events with basic and advanced filtering (mcp_google_calendar_find_events).
  • Create detailed events (mcp_google_calendar_create_event).
  • Quick-add events from text (mcp_google_calendar_quick_add_event).
  • Update events (mcp_google_calendar_update_event).
  • Delete events (mcp_google_calendar_delete_event).
  • Add attendees to events (mcp_google_calendar_add_attendee).
• Advanced Scheduling & Analysis:
  • Check attendee response status (mcp_google_calendar_check_attendee_status).
  • Query free/busy information for multiple calendars (mcp_google_calendar_query_free_busy).
  • Find mutual free slots and schedule meetings automatically (mcp_google_calendar_schedule_mutual).
  • Analyze daily event counts and durations (mcp_google_calendar_analyze_busyness).
  • (Recurring event projection feature potentially added in Task 3.5, but not explicitly exposed as a tool yet)
• Server: FastAPI-based server exposing actions via a RESTful API.
• MCP Integration: Provides MCP-compatible tools via stdio using the mcp_sdk library.

Setup

1. Prerequisites:
   • Python 3.8+ installed.
   • Git installed.
   • Access to a Google Cloud Platform project.
2. Clone Repository:
   git clone <repository-url> # Replace with your repo URL cd <repository-directory>
3. Google Cloud Setup (OAuth Credentials):
   • Go to the Google Cloud Console.
   • Create a new project or select an existing one.
   • Enable the Google Calendar API for your project.
   • Navigate to "APIs & Services" > "Credentials".
   • Click "+ CREATE CREDENTIALS" > "OAuth client ID".
   • Select Application type: Desktop app. Give it a name (e.g., "Calendar MCP Local").
   • Click "CREATE". A pop-up will show your Client ID and Client Secret. Copy these now - you'll need them for the .env file. You do not need to download the JSON file offered for other app types.
   • Configure the OAuth consent screen:
     • Set User Type to "External".
     • Fill in required app info (App name, User support email, Developer contact).
     • Add Scopes: Click "Add or Remove Scopes", search for calendar, add the .../auth/calendar scope (read/write access). Click "Update".
     • Add Test Users: Add the Google Account email address(es) you will authenticate with.
     • Save and return to the dashboard.
   • Go back to "APIs & Services" > "Credentials" and click on the name of the Desktop App credential you created.
   • Under "Authorized redirect URIs", click "+ ADD URI" and enter http://localhost:8080/oauth2callback. Click "Save". (Adjust the port if you change OAUTH_CALLBACK_PORT in .env).
4. Environment Configuration (.env file):
   • In the project's root directory, copy the env.example file and rename the copy to .env.
   • Open the .env file and paste your Client ID and Client Secret obtained from Google Cloud:
     # Google OAuth 2.0 Client Credentials (from Google Cloud Console - Desktop app type) GOOGLE_CLIENT_ID='YOUR_GOOGLE_CLIENT_ID_HERE' GOOGLE_CLIENT_SECRET='YOUR_GOOGLE_CLIENT_SECRET_HERE' # Path to the file where the user's OAuth tokens will be stored after first auth # This file is created automatically. Default is .gcp-saved-tokens.json TOKEN_FILE_PATH='.gcp-saved-tokens.json' # Port for the local webserver during the OAuth callback (must match Google Cloud redirect URI) OAUTH_CALLBACK_PORT=8080 # Google Calendar API Scopes (read/write is default) # Use 'https://www.googleapis.com/auth/calendar.readonly' for read-only access CALENDAR_SCOPES='https://www.googleapis.com/auth/calendar'
   • Ensure TOKEN_FILE_PATH points to a location where the app can write the token file (the default .gcp-saved-tokens.json in the root is usually fine). This file is automatically added to .gitignore.
5. Install Dependencies:
   • Navigate to the project directory in your terminal.
   • Install the required Python packages:
     pip install -r requirements.txt
   • (Using a Python virtual environment is recommended but optional)

Running the Server (for Initial Authentication & Testing)

You only need to run the server manually once to complete the initial Google OAuth authentication flow. After that, your MCP client will launch the server automatically using the command specified in its configuration.

1. First Run (Authentication):
   • Run the server script from your terminal:
     python run_server.py
   • The script checks for saved tokens (.gcp-saved-tokens.json). Since they don't exist yet, it will:
     • Print an authorization URL.
     • Automatically open your browser to that URL.
     • Guide you through logging into your Google Account and granting calendar permissions.
     • After you grant permissions, Google redirects back to a local URL (http://localhost:8080/oauth2callback).
     • The script captures the authorization code and saves the necessary tokens to the file specified in .env (.gcp-saved-tokens.json).
   • Once tokens are saved, the script will typically start the FastAPI server (e.g., on http://localhost:8000). You can usually stop it (Ctrl+C) after you see confirmation that tokens were saved or the server has started.
2. Optional: Testing the Server Directly:
   • If you want to test the FastAPI server directly (e.g., by sending HTTP requests with tools like curl or Postman), you can run python run_server.py again. It will load the saved tokens and start the server without requiring browser authentication.

Note: For regular use with an MCP client, you do not need to run python run_server.py manually after the initial authentication. The client handles launching it.

MCP Client Configuration (Example for Cursor/Claude Desktop)

To use this server as a tool within an MCP client, you need to configure the client to run the run_server.py script. This is typically done in a JSON settings file.

Example mcp.json Entry:

Configuration Details:

• google_calendar: A unique name you choose for this tool instance within your MCP client.
• command: Set this to python if it's in your system's PATH. If not, provide the full absolute path to the python.exe or python executable (e.g., /path/to/your/venv/bin/python or C:/path/to/your/venv/Scripts/python.exe).
• args: Provide the full, absolute path to the run_server.py script in your project directory. Replace the placeholder /path/to/your/calendar-mcp/run_server.py with the actual path on your system.
• (Optional) api: Some clients might still need the api field to point to the underlying FastAPI server (e.g., "api": "http://localhost:8000") for schema discovery, even though communication happens via stdio.
• (Optional) timeout: You can add a timeout (e.g., "timeout": 30000 for 30 seconds).

How it Works: When the MCP client invokes this tool, it executes the specified command with the args. The run_server.py script detects it's being run this way (via piped stdin/stdout) and automatically starts the MCP communication bridge instead of just the HTTP server.

Important:

• Your Google Client ID/Secret remain secure in your project's .env file, not in the MCP client configuration.
• Consult your specific MCP client's documentation for the exact configuration file location and required fields.

Development

• Code Structure:
  • run_server.py: Main entry point, handles server startup and MCP detection.
  • src/server.py: FastAPI application definition, HTTP endpoints.
  • src/calendar_actions.py: Core logic interacting with the Google Calendar API.
  • src/analysis.py: Advanced analysis functions.
  • src/auth.py: Handles OAuth 2.0 authentication flow and token management.
  • src/models.py: Pydantic models for request/response data structures.
  • src/mcp_bridge.py: Implements the MCP tool definitions using mcp_sdk, delegating to the FastAPI server.
• Logging: Logs are written to calendar_mcp.log in the project root.
• Testing: (Details TBD)
• Contributing: (Details TBD)

Next Steps (Planned Tasks)

• Implement MCP Resources/Prompts support (Task 6.1, 6.2).
• Enhance MCP tool argument validation and response formatting (Task 6.3, 6.4).
• Improve MCP error handling (Task 6.5).
• Refine development workflow (Task 7).

License

This project is dual-licensed to support both open-source collaboration and sustainable development:

1. GNU Affero General Public License v3.0 (AGPL-3.0):
   • This software is free to use, modify, and distribute under the terms of the AGPLv3 license.
   • Key conditions include that derivative works (including modifications used over a network) must also be licensed under AGPLv3 and their source code made available.
   • This license is suitable for open-source projects or internal use where AGPLv3 compliance is feasible.
   • See the LICENSE file for the full text.
2. Commercial License:
   • If the terms of the AGPLv3 are not suitable for your specific use case (e.g., integrating this software into a proprietary, closed-source commercial product or service without complying with AGPLv3's source-sharing requirements), a separate commercial license is available.
   • Please contact deciduusleaf@gmail.com for inquiries regarding commercial licensing options.

By using, modifying, or distributing this software, you agree to be bound by the terms of either the AGPLv3 or a separately negotiated commercial license.