peadams21/Google-Calendar-MCP-Server

Google Calendar MCP Server

A Model Context Protocol (MCP) server that provides comprehensive Google Calendar integration capabilities. This server allows AI assistants and applications to interact with Google Calendar through a standardized protocol.

Features

• List Events: Retrieve events from Google Calendar with filtering options
• Create Events: Create new calendar events with full customization
• Update Events: Modify existing calendar events
• Delete Events: Remove events from calendars
• List Calendars: Get available calendars for the authenticated user
• OAuth Authentication: Secure Google Calendar API access

Tools Available

list_events

Retrieve events from a Google Calendar with various filtering options.

Parameters:

• calendarId (optional): Calendar ID (default: "primary")
• timeMin (optional): Lower bound for event start time (RFC3339 timestamp)
• timeMax (optional): Upper bound for event start time (RFC3339 timestamp)
• maxResults (optional): Maximum number of events (default: 250)
• singleEvents (optional): Expand recurring events (default: true)
• orderBy (optional): Order events by "startTime" or "updated"

create_event

Create a new event in Google Calendar.

Parameters:

• calendarId (optional): Calendar ID (default: "primary")
• summary (required): Event title
• description (optional): Event description
• start (required): Start date/time object with dateTime and optional timeZone
• end (required): End date/time object with dateTime and optional timeZone
• location (optional): Event location
• attendees (optional): Array of attendee objects with email and displayName
• recurrence (optional): Array of RRULE strings for recurring events

update_event

Update an existing calendar event.

Parameters:

• calendarId (optional): Calendar ID (default: "primary")
• eventId (required): ID of the event to update
• summary (optional): New event title
• description (optional): New event description
• start (optional): New start date/time
• end (optional): New end date/time
• location (optional): New event location
• attendees (optional): New attendees list

delete_event

Delete an event from Google Calendar.

Parameters:

• calendarId (optional): Calendar ID (default: "primary")
• eventId (required): ID of the event to delete

list_calendars

List available Google Calendars for the authenticated user.

Parameters:

• minAccessRole (optional): Minimum access role filter
• showDeleted (optional): Include deleted calendars (default: false)
• showHidden (optional): Include hidden calendars (default: false)

Setup

Prerequisites

1. Google Cloud Project: Create a project in Google Cloud Console
2. Enable Google Calendar API: Enable the Calendar API for your project
3. Service Account: Create a service account and download the JSON key file

Installation

1. Clone this repository

2. Install dependencies:

   npm install
   

3. Copy the environment file and configure:

   copy .env.example .env
   

4. Edit .env and set your Google Service Account key file path:

   GOOGLE_SERVICE_ACCOUNT_KEY_FILE=./path/to/your/service-account-key.json
   

Building

# Build the TypeScript code
npm run build

# Development mode with hot reload
npm run dev

# Type checking
npm run type-check

# Clean build artifacts
npm run clean

Usage

Running the Server

# Start the compiled server
npm start

# Or run in development mode
npm run dev

Integrating with MCP Clients

Add this server to your MCP client configuration:

{
  "servers": {
    "google-calendar": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

For VS Code with MCP extension, add to .vscode/mcp.json:

{
  "servers": {
    "google-calendar-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

Authentication Setup

1. Create a Service Account:

   • Go to Google Cloud Console
   • Navigate to IAM & Admin > Service Accounts
   • Create a new service account
   • Download the JSON key file

2. Share Calendar Access:

   • Open Google Calendar
   • Go to calendar settings
   • Share your calendar with the service account email
   • Grant "Make changes to events" permission

3. Configure Environment:

   • Place the JSON key file in your project directory
   • Update the .env file with the correct path

Development

Project Structure

src/
├── index.ts          # Main MCP server implementation
├── types/            # TypeScript type definitions
└── utils/            # Utility functions

.env.example          # Environment variable template
tsconfig.json         # TypeScript configuration
package.json          # Node.js dependencies and scripts

Adding New Tools

1. Define a Zod schema for input validation
2. Create a ToolSchema definition
3. Implement the async handler function
4. Register the tool in the server
5. Add comprehensive error handling

Error Handling

All tools return structured responses:

// Success response
{
  content: [{ type: "text", text: JSON.stringify(result) }]
}

// Error response
{
  content: [{ type: "text", text: JSON.stringify(error) }],
  isError: true
}

Security Considerations

• Never commit service account keys to version control
• Use environment variables for all sensitive configuration
• Implement proper error handling to avoid information leakage
• Regularly rotate service account keys
• Follow Google Cloud security best practices

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with proper tests
4. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

• Check the Google Calendar API documentation
• Review MCP specification
• Open an issue in this repository