calendar-mcp

Google Calendar AutoAuth MCP Server

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

Features

• Create calendar events with title, description, location, and attendees
• Update existing calendar events
• Delete calendar events
• Retrieve event details
• List events within a specified time range
• Search for events by keyword
• List all available calendars
• Support for natural language date/time input (e.g., "tomorrow at 2pm", "next monday")
• Full integration with Google Calendar API
• Simple OAuth2 authentication flow with auto browser launch
• Support for both Desktop and Web application credentials
• Global credential storage for convenience

Installation & Authentication

Installing Manually

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 either "Desktop app" or "Web application" as application type
   • Give it a name and click "Create"
   • For Web application, add http://localhost:3000/oauth2callback to the authorized redirect URIs
   • Download the JSON file of your client's OAuth keys
   • Rename the key file to gcp-oauth.keys.json
2. Run Authentication: You can authenticate in two ways: a. Global Authentication (Recommended):

   # First time: Place gcp-oauth.keys.json in your home directory's .calendar-mcp folder
   mkdir -p ~/.calendar-mcp
   mv gcp-oauth.keys.json ~/.calendar-mcp/
    
   # Run authentication from anywhere
   npx @nchufa/calendar auth

   Copy

   b. Local Authentication:

   # Place gcp-oauth.keys.json in your current directory
   # The file will be automatically copied to global config
   npx @nchufa/calendar auth

   Copy

   The authentication process will:
   • Look for gcp-oauth.keys.json in the current directory or ~/.calendar-mcp/
   • If found in current directory, copy it to ~/.calendar-mcp/
   • Open your default browser for Google authentication
   • Save credentials as ~/.calendar-mcp/credentials.json

   Note:

   • After successful authentication, credentials are stored globally in ~/.calendar-mcp/ and can be used from any directory
   • Both Desktop app and Web application credentials are supported
   • For Web application credentials, make sure to add http://localhost:3000/oauth2callback to your authorized redirect URIs
3. Configure in Claude Desktop: Add the following to your Claude Desktop configuration file:

{
  "mcpServers": {
    "calendar": {
      "command": "npx",
      "args": [
        "@nchufa/calendar"
      ]
    }
  }
}

Available Tools

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

1. Create Event (create_event)

Creates a new calendar event.

{
  "summary": "Team Meeting",
  "description": "Weekly team sync to discuss project progress",
  "location": "Conference Room A",
  "start": "2025-04-01T14:00:00",
  "end": "2025-04-01T15:00:00",
  "attendees": ["[email protected]", "[email protected]"],
  "reminders": {
    "useDefault": false,
    "overrides": [
      {
        "method": "email",
        "minutes": 30
      },
      {
        "method": "popup",
        "minutes": 10
      }
    ]
  }
}

Natural language date/time is also supported:

{
  "summary": "Coffee with John",
  "location": "Starbucks Downtown",
  "start": "tomorrow at 2:30pm",
  "end": "tomorrow at 3:30pm"
}

2. Get Event (get_event)

Retrieves details of a specific calendar event.

{
  "eventId": "abc123xyz456",
  "calendarId": "primary"
}

3. Update Event (update_event)

Updates an existing calendar event.

{
  "eventId": "abc123xyz456",
  "summary": "Updated Meeting Title",
  "location": "New Location",
  "start": "2025-04-01T15:00:00",
  "end": "2025-04-01T16:00:00"
}

4. Delete Event (delete_event)

Deletes a calendar event.

{
  "eventId": "abc123xyz456",
  "calendarId": "primary"
}

5. List Events (list_events)

Lists calendar events within a specified time range.

{
  "calendarId": "primary",
  "timeMin": "2025-04-01T00:00:00",
  "timeMax": "2025-04-07T23:59:59",
  "maxResults": 10,
  "orderBy": "startTime"
}

6. Search Events (search_events)

Searches for events matching a query.

{
  "query": "meeting",
  "calendarId": "primary",
  "timeMin": "2025-04-01T00:00:00",
  "maxResults": 5
}

7. List Calendars (list_calendars)

Lists all available calendars.

{}

Natural Language Date/Time Support

The server supports various natural language formats for dates and times:

• Specific dates: "2025-04-01T14:00:00" (ISO format)
• Simple references: "today", "tomorrow", "now"
• Relative times: "2 hours later", "3 days later"
• Day references: "next monday", "next tuesday"
• Combined formats: "tomorrow at 2pm", "monday at 15:30"

This makes it easy to create and update events using natural language instructions.

Security Notes

• OAuth credentials are stored securely in your local environment (~/.calendar-mcp/)
• The server uses offline access to maintain persistent authentication
• Never share or commit your credentials to version control
• Regularly review and revoke unused access in your Google Account settings

Troubleshooting

1. OAuth Keys Not Found
   • Make sure gcp-oauth.keys.json is in either your current directory or ~/.calendar-mcp/
   • Check file permissions
2. Invalid Credentials Format
   • Ensure your OAuth keys file contains either web or installed credentials
   • For web applications, verify the redirect URI is correctly configured
3. Port Already in Use
   • If port 3000 is already in use, please free it up before running authentication
   • You can find and stop the process using that port

Contributing

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

License

MIT

Acknowledgments

Special thanks to GongRzhe and his Calendar-Autoauth-MCP-Server project which served as a foundation for this implementation.

Support

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