# Google Calendar MCP Server

A Model Context Protocol (MCP) server for managing Google Calendar events.

## Features

- List, create, update, delete, and get calendar events
- OAuth 2.0 and Service Account authentication
- Docker support for easy deployment
- MCP client integration (Cursor, Claude Desktop)

## Quick Start

```bash
# Install dependencies
npm install

# Authenticate with Google
npm run auth

# Build and run
npm run build
npm start
```

For Docker: See [DOCKER.md](DOCKER.md)

## Project Structure

```
googlecalendar-mcp/
├── src/
│   ├── index.ts           # Main MCP server
│   └── auth-helper.ts     # OAuth authentication helper
├── dist/                  # Compiled JavaScript (generated)
├── .env                   # Environment variables (create from .env.example)
├── package.json           # Node.js dependencies
├── tsconfig.json          # TypeScript configuration
├── Dockerfile             # Docker build configuration
├── docker-compose.yml     # Docker Compose setup
├── docker-helper.sh       # Docker convenience script
├── README.md              # This file
└── DOCKER.md              # Docker-specific documentation
```

## Prerequisites

- Node.js 18+
- Google Cloud Project with Calendar API enabled
- OAuth 2.0 credentials

## Setup

### 1. Set Up Google Calendar API

#### 1.1 Create or Select a Project

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Click on the project dropdown at the top of the page
3. Either:
   - **Create a new project**: Click "New Project", enter a project name (e.g., "Google Calendar MCP"), and click "Create"
   - **Select an existing project**: Choose from the list of existing projects

#### 1.2 Enable Google Calendar API

1. In the Google Cloud Console, navigate to **"APIs & Services" > "Library"** (or use the search bar)
2. Search for **"Google Calendar API"**
3. Click on **"Google Calendar API"** from the search results
4. Click the **"Enable"** button
5. Wait for the API to be enabled (this usually takes a few seconds)
6. You should see a confirmation message: "API enabled"

**Alternative Method:**
- You can also enable it directly via this link (replace `YOUR_PROJECT_ID` with your actual project ID):
  ```
  https://console.cloud.google.com/apis/library/calendar-json.googleapis.com?project=YOUR_PROJECT_ID
  ```

**Troubleshooting:**
- If you see an error like "Google Calendar API has not been used in project X before or it is disabled", make sure you've completed the steps above
- After enabling, wait a few minutes for the changes to propagate across Google's systems
- Verify the API is enabled by checking "APIs & Services" > "Enabled APIs" - you should see "Google Calendar API" listed

#### 1.3 Create OAuth 2.0 Credentials

1. Navigate to **"APIs & Services" > "Credentials"** in the Google Cloud Console
2. If this is your first time, you may need to configure the OAuth consent screen:
   - Click **"Configure Consent Screen"**
   - Choose **"External"** (unless you have Google Workspace, then choose "Internal")
   - Fill in the required information:
     - App name: "Google Calendar MCP" (or any name you prefer)
     - User support email: Your email address
     - Developer contact information: Your email address
   - Click **"Save and Continue"** through the steps (you can skip optional steps for now)
3. Go back to **"Credentials"** and click **"Create Credentials" > "OAuth client ID"**
4. If prompted, choose **"Desktop app"** as the application type
5. Enter a name for your OAuth client (e.g., "Google Calendar MCP Client")
6. Click **"Create"**
7. **Important**: Copy the **Client ID** and **Client Secret** immediately - you'll need these for your `.env` file
8. Click **"OK"** to close the dialog

**Note**: The Client ID and Client Secret are sensitive credentials. Keep them secure and never commit them to version control.

### 2. Configure Environment Variables

Create a `.env` file in the root directory:

```env
# Google Calendar API Credentials
GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback

# OAuth2 Token (will be generated after first authentication)
GOOGLE_ACCESS_TOKEN=
GOOGLE_REFRESH_TOKEN=

# Optional: Service Account JSON file path (alternative to OAuth)
# GOOGLE_SERVICE_ACCOUNT_PATH=./service-account.json

# Calendar ID (default is 'primary' for the primary calendar)
CALENDAR_ID=primary
```

### 3. Install Dependencies & Authenticate

```bash
npm install
```

Then authenticate:

If using OAuth 2.0, you can use the included authentication helper:

```bash
npm run auth
```

This will:
1. **Automatically start a local HTTP server** to catch the OAuth redirect
2. **Open your browser** with the authorization URL (or show you the URL to copy)
3. After you authorize, **automatically capture the authorization code**
4. **Exchange the code for tokens** automatically
5. **Update your `.env` file** with the tokens

**Note**: Make sure `http://localhost:3000/oauth2callback` is added to your OAuth client's authorized redirect URIs in Google Cloud Console.

**Alternative: Manual Authentication**

You can also use the Google OAuth 2.0 Playground:

1. Visit [Google OAuth 2.0 Playground](https://developers.google.com/oauthplayground/)
2. Select "Calendar API v3" scopes
3. Authorize and get your tokens
4. Add the tokens to your `.env` file

### 4. Build the Project

```bash
npm run build
```

## Usage

### Running the Server

```bash
npm start
```

Or for development with auto-reload:

```bash
npm run dev
```

The server runs on stdio and communicates via the MCP protocol.

### Available Tools

#### `list_events`

List events from Google Calendar.

**Parameters:**
- `timeMin` (optional): Lower bound for event end time (ISO 8601 format)
- `timeMax` (optional): Upper bound for event start time (ISO 8601 format)
- `maxResults` (optional): Maximum number of events (default: 10)
- `calendarId` (optional): Calendar ID (default: "primary")

**Example:**
```json
{
  "timeMin": "2024-01-01T00:00:00Z",
  "timeMax": "2024-12-31T23:59:59Z",
  "maxResults": 20
}
```

#### `create_event`

Create a new event in Google Calendar.

**Parameters:**
- `summary` (required): Title of the event
- `startDateTime` (required): Start date/time (ISO 8601 format)
- `endDateTime` (required): End date/time (ISO 8601 format)
- `description` (optional): Event description
- `location` (optional): Event location
- `timeZone` (optional): Time zone (default: "UTC")
- `attendees` (optional): Array of attendee email addresses
- `calendarId` (optional): Calendar ID (default: "primary")

**Example:**
```json
{
  "summary": "Team Meeting",
  "description": "Weekly team sync",
  "startDateTime": "2024-01-15T10:00:00Z",
  "endDateTime": "2024-01-15T11:00:00Z",
  "timeZone": "America/New_York",
  "location": "Conference Room A",
  "attendees": ["colleague@example.com"]
}
```

#### `update_event`

Update an existing event.

**Parameters:**
- `eventId` (required): ID of the event to update
- All other parameters are optional (same as `create_event`)

#### `delete_event`

Delete an event from the calendar.

**Parameters:**
- `eventId` (required): ID of the event to delete
- `calendarId` (optional): Calendar ID (default: "primary")

#### `get_event`

Get details of a specific event.

**Parameters:**
- `eventId` (required): ID of the event to retrieve
- `calendarId` (optional): Calendar ID (default: "primary")

## MCP Client Configuration

Add to your MCP client config (Cursor, Claude Desktop):

```json
{
  "mcpServers": {
    "google-calendar": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_ACCESS_TOKEN": "your_access_token",
        "GOOGLE_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}
```

For Docker setup, see [DOCKER.md](DOCKER.md)

## Troubleshooting

### "Google Calendar API has not been used in project X before or it is disabled"

This error means the Google Calendar API is not enabled in your Google Cloud project.

**Solution:**
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Select your project
3. Navigate to **"APIs & Services" > "Library"**
4. Search for "Google Calendar API" and enable it
5. Wait a few minutes for the changes to propagate
6. Retry your request

**Direct link to enable API:**
Replace `YOUR_PROJECT_ID` with your actual project ID:
```
https://console.cloud.google.com/apis/library/calendar-json.googleapis.com?project=YOUR_PROJECT_ID
```

### "Missing Google OAuth credentials" error

- Check that `.env` file exists and has correct values
- Verify `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are set
- Make sure there are no extra spaces or quotes around the values
- Ensure the `.env` file is in the project root directory

### "Invalid credentials" error

- Verify your Client ID and Client Secret are correct
- Check that Google Calendar API is enabled in your project
- Ensure OAuth consent screen is configured
- Make sure you're using the correct project credentials

### "Token expired" error

- Re-run `npm run auth` to get new tokens
- Or use [Google OAuth 2.0 Playground](https://developers.google.com/oauthplayground/) to refresh tokens
- Update your `.env` file with the new tokens

### Server won't start

- Check Node.js version: `node --version` (needs 18+)
- Rebuild the project: `npm run build`
- Check for errors: `npm start`
- Verify all dependencies are installed: `npm install`

### MCP Server Connection Issues

- Verify the path in `mcp.json` is correct and uses absolute paths
- Check that `dist/index.js` exists (run `npm run build` if missing)
- Ensure environment variables are properly set in your MCP configuration
- Restart your MCP client (Cursor/Claude Desktop) after configuration changes

## Alternative: Service Account

For server-to-server authentication:
1. Create a service account in Google Cloud Console
2. Download the JSON key file
3. Share your calendar with the service account email
4. Set `GOOGLE_SERVICE_ACCOUNT_PATH` in `.env`

## Development

```bash
npm run dev  # Development mode with auto-reload
```

## License

MIT