PabloSR06/mcp-google-calendar

mcp-google-calendar

A Google Calendar and Google Tasks (MCP) server to expose calendar and task operations as tools for LLM.

Table of Contents

• mcp-google-calendar
  • Table of Contents
  • Important: Authentication Architecture
    • Current Implementation
    • Multi-User Scenarios
  • Setup
    • Prerequisites
    • Step-by-step Configuration
      • 1. Configure Google Cloud Console Project
      • 2. Create OAuth 2.0 Credentials
      • 3. Configure the .env file
      • 4. Get the refresh token
      • 5. Test the configuration
    • MCP Client Configuration
  • Usage
  • Testing with MCP Inspector
  • Timezone Configuration
  • Security
  • Additional Resources
  • Available Tools
    • Calendar Tools
      • calendar-create-event
      • calendar-update-event
      • calendar-list-events
      • calendar-search-events
      • calendar-delete-event
      • calendar-list-calendars
      • calendar-get-current-datetime
    • Tasks Tools
      • tasks-list-task-lists
      • tasks-list-tasks
      • tasks-create-task
      • tasks-update-task
      • tasks-delete-task
  • License

Important: Authentication Architecture

This MCP server is configured to use a single Google account for all operations. The authentication credentials (client ID, client secret, and refresh token) are stored in environment variables (.env file), meaning all users of this MCP server will interact with the same Google Calendar and Google Tasks account.

Current Implementation

• Single Account Mode: One Google account's credentials are configured in the .env file
• All operations (create, read, update, delete events and tasks) are performed on this single account
• Best for: Personal use, single-user applications, or shared team calendars and task lists

Multi-User Scenarios

If you need each user to authenticate with their own Google account, this server would require modifications:

1. Add user authentication layer: Implement a user authentication system (OAuth2, sessions, JWT, etc.)
2. Pass user context: Modify the MCP tools to use the authenticated user's token instead of the .env token
3. Token refresh logic: Implement per-user token refresh and management

Note: The current implementation prioritizes simplicity for personal use.

Setup

Prerequisites

1. A Google account
2. Access to Google Cloud Console
3. Node.js installed

Step-by-step Configuration

1. Configure Google Cloud Console Project

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the required APIs:
   • Google Calendar API: Go to "APIs & Services" > "Library", search for "Google Calendar API" and click "Enable"
   • Google Tasks API: Go to "APIs & Services" > "Library", search for "Google Tasks API" and click "Enable"

2. Create OAuth 2.0 Credentials

1. Go to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "OAuth 2.0 Client ID"
3. If it's your first time, configure the OAuth consent screen:
   • Select "External" (or "Internal" if you have Google Workspace)
   • Complete the basic app information
   • In "Scopes", don't add any scope (we'll do this programmatically)
   • Add your email as a test user
4. Create the OAuth 2.0 Client ID:
   • Application type: "Web application"
   • Name: "Google Calendar MCP Server"
   • Authorized redirect URIs: http://localhost:8080/oauth/callback

3. Configure the .env file

1. Copy the credentials from Google Cloud Console
2. Create a .env file in the project root:

# Google Cloud Console credentials
GOOGLE_CLIENT_ID=your_client_id_here.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_client_secret_here

# This will be generated in the next step
GOOGLE_REFRESH_TOKEN=

# Default timezone for calendar operations
DEFAULT_TIMEZONE=Atlantic/Canary

4. Get the refresh token

Run the setup script:

npm run setup:google

This script will:

1. Start a temporary server on port 8080
2. Show you a URL to authorize the application
3. Open that URL in your browser
4. After authorizing, give you a refresh_token
5. Return token GOOGLE_REFRESH_TOKEN

5. Test the configuration

npm run build
node dist/index.js

MCP Client Configuration

Add this to your MCP client configuration (e.g., Claude Desktop config):

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      //WIP: "args": ["mcp-google-calendar"],
      "env": {
        "GOOGLE_CLIENT_ID": "<your-client-id>",
        "GOOGLE_CLIENT_SECRET": "<your-client-secret>",
        "GOOGLE_REFRESH_TOKEN": "<your-refresh-token>",
        "DEFAULT_TIMEZONE": "Atlantic/Canary"
      }
    }
  }
}

Usage

1. Compile TypeScript to JavaScript:

npm run build

2. Run the MCP server:

node dist/index.js

Testing with MCP Inspector

You can test and debug this MCP server using the MCP Inspector:

1. Make sure you have built the project:

npm run build

2. Set up your environment variables in .env file:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REFRESH_TOKEN=your-refresh-token
DEFAULT_TIMEZONE=Atlantic/Canary

3. Update mcp-inspector-config.json with your project path:

{
  "mcpServers": {
    "mcp-google-calendar": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "${GOOGLE_CLIENT_ID}",
        "GOOGLE_CLIENT_SECRET": "${GOOGLE_CLIENT_SECRET}",
        "GOOGLE_REFRESH_TOKEN": "${GOOGLE_REFRESH_TOKEN}",
        "DEFAULT_TIMEZONE": "${DEFAULT_TIMEZONE}"
      }
    }
  }
}

4. Run the MCP Inspector:

npx @modelcontextprotocol/inspector --config mcp-inspector-config.json

1. Open your browser to the URL shown in the terminal (default should be http://localhost:6277) to interact with the MCP server through the Inspector UI.

Timezone Configuration

This MCP server supports flexible timezone configuration:

1. Default Timezone: Set DEFAULT_TIMEZONE in your .env file using IANA timezone format (e.g., Atlantic/Canary, America/New_York, Asia/Tokyo)
2. Per-Operation Override: When creating or updating events, you can specify a different timezone for that specific operation
3. Fallback: If no timezone is configured, the server defaults to Atlantic/Canary

Timezone Priority:

1. Timezone parameter passed to the tool (highest priority)
2. DEFAULT_TIMEZONE environment variable from .env
3. Hardcoded default: Atlantic/Canary (lowest priority)

Common IANA Timezones:

• Europe: Atlantic/Canary, Europe/London, Europe/Paris, Europe/Berlin
• Americas: America/New_York, America/Chicago, America/Los_Angeles, America/Mexico_City
• Asia: Asia/Tokyo, Asia/Shanghai, Asia/Dubai, Asia/Kolkata
• Other: Atlantic/Canary, Pacific/Auckland, Australia/Sydney

Security

• Never share your client_secret or refresh_token
• Add .env to your .gitignore (already included)
• Tokens have limited permissions only for Google Calendar and Google Tasks

Additional Resources

• Google Calendar API Documentation
• Google Tasks API Documentation
• OAuth 2.0 for Web Server Applications
• Google Cloud Console
• Model Context Protocol Documentation

Available Tools

Calendar Tools

calendar-create-event

Creates a new calendar event in Google Calendar.

Parameters:

• title: String - Event title/summary
• start: DateTime string - Event start time (ISO 8601 format)
• end: DateTime string - Event end time (ISO 8601 format)
• description: String (optional) - Event description
• location: String (optional) - Event location
• attendees: Array of email strings (optional) - List of attendee email addresses
• timeZone: String (optional) - Timezone in IANA format (e.g., Atlantic/Canary, America/New_York). Defaults to DEFAULT_TIMEZONE from .env or 'Atlantic/Canary'
• calendarId: String (optional) - Calendar ID (defaults to 'primary')

Returns:

• The unique ID and details of the created event

calendar-update-event

Updates an existing event in Google Calendar.

Parameters:

• eventId: String - The unique ID of the event to update
• title: String (optional) - New event title/summary
• start: DateTime string (optional) - New event start time (ISO 8601 format)
• end: DateTime string (optional) - New event end time (ISO 8601 format)
• description: String (optional) - New event description
• location: String (optional) - New event location
• attendees: Array of email strings (optional) - List of attendee email addresses
• timeZone: String (optional) - Timezone in IANA format (e.g., Atlantic/Canary, America/New_York). Defaults to DEFAULT_TIMEZONE from .env or 'Atlantic/Canary'
• calendarId: String (optional) - Calendar ID (defaults to 'primary')

Returns:

• The updated event details

calendar-list-events

Lists events within a specified timeframe from Google Calendar.

Parameters:

• timeMin: DateTime string (optional) - Start of the timeframe (ISO 8601 format)
• timeMax: DateTime string (optional) - End of the timeframe (ISO 8601 format)
• calendarId: String (optional) - Calendar ID (defaults to 'primary')
• maxResults: Number (optional) - Maximum number of events to return (default: 10)

Returns:

• A list of events that fall within the given timeframe

calendar-search-events

Searches for events in Google Calendar by text query.

Parameters:

• query: String - Search query
• calendarId: String (optional) - Calendar ID (defaults to 'primary')
• maxResults: Number (optional) - Maximum number of events to return (default: 10)

Returns:

• A list of events matching the search query

calendar-delete-event

Deletes an event from Google Calendar.

Parameters:

• eventId: String - The unique ID of the event to delete
• calendarId: String (optional) - Calendar ID (defaults to 'primary')

Returns:

• Confirmation of deletion

calendar-list-calendars

Lists all calendars available to the user.

Returns:

• A list of calendars with their IDs and names

calendar-get-current-datetime

Gets the current date and time in ISO 8601 format. Useful for references when creating or searching for events.

Parameters:

• timezone: String (optional) - Timezone in IANA format (e.g., Atlantic/Canary, America/New_York, Asia/Tokyo). Defaults to DEFAULT_TIMEZONE from .env or 'Atlantic/Canary'.

Returns:

• Current date and time information including ISO 8601 format, timestamp, local time, and timezone details

Tasks Tools

tasks-list-task-lists

Lists all task lists available in Google Tasks.

Parameters: None

Returns:

• A list of all task lists with their IDs and titles

Example use case:

• Get the list of all your task lists to find the taskListId for creating or managing tasks

tasks-list-tasks

Lists all tasks in a specific task list.

Parameters:

• taskListId: String - The ID of the task list (use tasks-list-task-lists to get this)
• showCompleted: Boolean (optional) - Whether to show completed tasks (default: true)
• maxResults: Number (optional) - Maximum number of tasks to return (default: 100)

Returns:

• A list of tasks with details including ID, title, notes, status, due date, and completion date

tasks-create-task

Creates a new task in Google Tasks.

Parameters:

• taskListId: String - The ID of the task list where the task will be created
• title: String - Task title/summary
• notes: String (optional) - Task notes or description
• due: DateTime string (optional) - Due date in ISO 8601 format (e.g., "2024-12-31T23:59:59Z")

Returns:

• The created task details including ID, title, notes, status, and due date

tasks-update-task

Updates an existing task in Google Tasks.

Parameters:

• taskListId: String - The ID of the task list containing the task
• taskId: String - The ID of the task to update
• title: String (optional) - New task title
• notes: String (optional) - New task notes or description
• due: DateTime string (optional) - New due date in ISO 8601 format
• status: String (optional) - Task status: either "needsAction" or "completed"

Returns:

• The updated task details

tasks-delete-task

Deletes a task from Google Tasks.

Parameters:

• taskListId: String - The ID of the task list containing the task
• taskId: String - The ID of the task to delete

Returns:

• Confirmation message of deletion

License

MIT