Calendar MCP Server

Calendar MCP Server

A Model Context Protocol (MCP) server for Google Calendar integration in Claude Desktop. This server enables AI assistants to manage Google Calendar events through natural language interactions.

npm version

License: ISC

Features

• Create calendar events with title, time, description, and location
• Retrieve event details by event ID
• Update existing events (title, time, description, location)
• Delete events
• List events within a specified time range
• Full integration with Google Calendar API
• Secure OAuth2 authentication

Installation

Installing via Smithery

To install Google Calendar Integration for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @gongrzhe/server-calendar-mcp --client claude

Manual Installation

npm install @gongrzhe/server-calendar-mcp

Setup

1. Create a Google Cloud Project and obtain credentials:

   a. Create a Google Cloud Project:

   • Go to Google Cloud Console
   • Create a new project or select an existing one
   • Enable the Google Calendar API for your project

   b. Create OAuth 2.0 Credentials:

   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Choose "Desktop app" as application type
   • Give it a name and click "Create"
   • You will get your GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET

   c. Get Refresh Token:

   • Go to OAuth 2.0 Playground
   • Click the gear icon (Settings) in the top right
   • Check "Use your own OAuth credentials"
   • Enter your OAuth Client ID and Client Secret
   • In the left panel, find "Calendar API v3" and select "https://www.googleapis.com/auth/calendar"
   • Click "Authorize APIs" and complete the OAuth flow
   • Click "Exchange authorization code for tokens"
   • Copy the "Refresh token" - this is your GOOGLE_REFRESH_TOKEN

2. Configure in Claude Desktop:

{
  "calendar": {
    "command": "npx",
    "args": [
      "@gongrzhe/server-calendar-mcp"
    ],
    "env": {
      "GOOGLE_CLIENT_ID": "your_client_id_here",
      "GOOGLE_CLIENT_SECRET": "your_client_secret_here",
      "GOOGLE_REFRESH_TOKEN": "your_refresh_token_here"
    }
  }
}

Usage Examples

The server provides several tools that can be used through the Claude Desktop:

Create Event

{
  "summary": "Team Meeting",
  "start": {
    "dateTime": "2024-01-20T10:00:00Z"
  },
  "end": {
    "dateTime": "2024-01-20T11:00:00Z"
  },
  "description": "Weekly team sync",
  "location": "Conference Room A"
}

List Events

{
  "timeMin": "2024-01-01T00:00:00Z",
  "timeMax": "2024-12-31T23:59:59Z",
  "maxResults": 10,
  "orderBy": "startTime"
}

Update Event

{
  "eventId": "event123",
  "summary": "Updated Meeting Title",
  "start": {
    "dateTime": "2024-01-20T11:00:00Z"
  },
  "end": {
    "dateTime": "2024-01-20T12:00:00Z"
  }
}

Delete Event

{
  "eventId": "event123"
}

Security Notes

• Keep your Google API credentials secure
• Regularly rotate your refresh tokens
• Store sensitive information in Claude Desktop configuration
• Never share or commit your credentials to version control
• The refresh token gives access to your Google Calendar, treat it like a password

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the ISC License.

Author

gongrzhe

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.