# 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](https://console.cloud.google.com)
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:
   ```bash
   npm install
   ```

3. Copy the environment file and configure:
   ```bash
   copy .env.example .env
   ```

4. Edit `.env` and set your Google Service Account key file path:
   ```env
   GOOGLE_SERVICE_ACCOUNT_KEY_FILE=./path/to/your/service-account-key.json
   ```

### Building

```bash
# 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

```bash
# 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:

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

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

```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](https://console.cloud.google.com)
   - 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:

```typescript
// 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](https://developers.google.com/calendar/api)
- Review [MCP specification](https://modelcontextprotocol.io)
- Open an issue in this repository