README.md•6.23 kB
# 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