Google Calendar MCP Server

🚀 Google Calendar MCP Server

A server that exposes Google Calendar tools to MCP-compatible clients, such as Claude Desktop and Cursor MCP CLI. It enables users to manage Google Calendar events efficiently.

🚀 Quick Start

This MCP server allows you to interact with Google Calendar through MCP-compatible clients. Here's what you can do:

• List events within a specified time frame.
• Create new events.
• Delete events by their summary.

📦 Installation

Prerequisites

• Python 3.11 or higher.
• A Google Cloud project with an OAuth 2.0 Client ID (Desktop) for the Google Calendar API.
• A locally downloaded credentials.json file (do not commit it to version control).

Setup Steps

1. Clone the repository and install dependencies

uv sync  # or: pip install -e .

2. Enable the Google Calendar API and download OAuth credentials
   • Navigate to the Google Cloud Console → APIs & Services → Credentials.
   • Create an OAuth client ID with the application type set to "Desktop app".
   • Download the JSON file and save it as credentials.json at the root of the project.
3. First run and OAuth consent The first time you call any tool, a browser window will open for you to provide consent. This will generate a token.json file locally, which should be ignored by git.

💻 Usage Examples

Running the MCP server

python -m src.service  # Not the server entry
python main.py         # Starts the MCP over stdio

To use the server with MCP-compatible clients, point them to main.py as the command.

Tools

• get_google_calendar_events(maxResults, calendarId="primary", singleEvents=True, orderBy="startTime", timeMin=None, timeMax=None)
  • Returns a list in the format: [{ "title": str, "start-time": str, "end-time": str }]
• create_google_calendar_event(summary, start: datetime, end: datetime, description=None, location=None, time_zone="Asia/Dhaka")
  • Returns the HTML link of the created event (if available).
• delete_google_calendar_event(event_name: str)
  • Deletes the first event with an exact summary match.

MCP client configuration (example)

Here is an example JSON snippet for a client configuration:

{
  "mcpServers": {
    "google-calendar": {
      "command": "python",
      "args": ["main.py"],
      "env": {}
    }
  }
}

📚 Documentation

Notes

• Keep credentials.json and token.json out of your git repository.
• Time strings must follow the RFC3339 format with a timezone (e.g., 2025-08-08T00:00:00+06:00).
• All-day events will return a date string instead of dateTime.