Integrations
Provides tools for managing Google Calendar, including listing calendars, creating events, finding events with filters, updating and deleting events, adding attendees, checking attendee status, querying free/busy information, scheduling mutual meetings, and analyzing calendar busyness.
Enables OAuth 2.0 authentication through Google Cloud Platform, allowing secure access to Google Calendar API with proper credentials and authorization.
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
).
- List calendars (
- 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)
- Check attendee response status (
- Server: FastAPI-based server exposing actions via a RESTful API.
- MCP Integration: Provides MCP-compatible tools via stdio using the
mcp_sdk
library.
Setup
- Prerequisites:
- Python 3.8+ installed.
- Git installed.
- Access to a Google Cloud Platform project.
- Clone Repository:Copy
- 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 changeOAUTH_CALLBACK_PORT
in.env
).
- 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:Copy - 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
.
- In the project's root directory, copy the
- Install Dependencies:
- Navigate to the project directory in your terminal.
- Install the required Python packages:Copy
- (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.
- First Run (Authentication):
- Run the server script from your terminal:Copy
- 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.
- Run the server script from your terminal:
- 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 runpython run_server.py
again. It will load the saved tokens and start the server without requiring browser authentication.
- If you want to test the FastAPI server directly (e.g., by sending HTTP requests with tools like
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 topython
if it's in your system's PATH. If not, provide the full absolute path to thepython.exe
orpython
executable (e.g.,/path/to/your/venv/bin/python
orC:/path/to/your/venv/Scripts/python.exe
).args
: Provide the full, absolute path to therun_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 theapi
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 usingmcp_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:
- 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.
- 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.
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
calendar-mcp
Related MCP Servers
- AsecurityAlicenseAqualityProvides tools for interacting with Gmail and Calendar APIs. This server enables you to manage your emails and calendar events programmatically through the MCP interface.Last updated -813JavaScriptMIT License
- -securityAlicense-qualityTransforms macOS calendar management into a conversational experience using natural language, allowing users to create, manage, and update calendar events seamlessly through an MCP-compatible client.Last updated -64PythonMIT License
- -securityAlicense-qualityEnables interaction with Gmail and Google Calendar using the MCP protocol, supporting multiple Google accounts, email management, and calendar operations through natural language.Last updated -5TypeScriptMIT License
- -securityFlicense-qualityAn MCP server that enables scheduling, updating, deleting, and listing calendar appointments through Cal.com's Calendar API.Last updated -JavaScript