musarratChowdhury/nodejs-mcp-server

Google Calendar MCP Server

A Model Context Protocol (MCP) server that integrates with Google Calendar to check for meetings scheduled this week.

Features

• Check Meetings: Quickly determine if you have any meetings this week
• List Meetings: Get detailed information about all meetings scheduled for the current week
• Google Calendar Integration: Secure OAuth2 authentication with Google Calendar API
• Smart Filtering: Automatically filters out busy blocks and focus time events

Prerequisites

1. Node.js: Version 18.0.0 or higher
2. Google Cloud Project: You'll need to create a Google Cloud project and enable the Calendar API
3. OAuth2 Credentials: Set up OAuth2 credentials in the Google Cloud Console

Setup

1. Install Dependencies

npm install

2. Google Cloud Setup

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Calendar API:
   • Go to "APIs & Services" > "Library"
   • Search for "Google Calendar API"
   • Click "Enable"
4. Create OAuth2 credentials:
   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth 2.0 Client IDs"
   • Choose "Desktop application"
   • Download the credentials JSON file

3. Environment Configuration

1. Copy the example environment file:

   cp env.example .env
   

2. Edit .env and add your Google OAuth2 credentials:

   GOOGLE_CLIENT_ID=your_client_id_here
   GOOGLE_CLIENT_SECRET=your_client_secret_here
   GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback
   

4. Authentication

1. Start the server:

   npm start
   

2. The server will display an authentication URL. Visit this URL in your browser.

3. After granting permissions, you'll receive an authorization code.

4. Authenticate using the code:

   node index.js auth YOUR_AUTHORIZATION_CODE
   

5. The token will be saved and you can now use the server normally.

Usage

Available Tools

1. check_meetings_this_week: Returns a simple yes/no answer about whether you have meetings this week
2. list_meetings_this_week: Provides detailed information about all meetings scheduled for the current week
3. authenticate_google_calendar: Authenticate with Google Calendar using an authorization code

Running the Server

npm start

Or for development with auto-restart:

npm run dev

How It Works

• Week Definition: The server considers a week from Sunday to Saturday
• Meeting Detection: Filters out all-day events, busy blocks, and focus time events
• Time Zone: Uses your system's local time zone for date calculations
• Authentication: Uses OAuth2 with offline access to maintain authentication across sessions

Security

• OAuth2 tokens are stored locally in token.json
• Only read-only access to your calendar is requested
• No calendar data is stored or transmitted outside of Google's servers

Troubleshooting

Authentication Issues

• Ensure your OAuth2 credentials are correctly configured
• Check that the redirect URI matches what's configured in Google Cloud Console
• Verify that the Google Calendar API is enabled in your project

No Meetings Found

• Check that you have meetings scheduled in your primary calendar
• Verify the time zone settings
• Ensure meetings are not marked as all-day events

Permission Errors

• Make sure you granted the necessary permissions during OAuth flow
• Check that the Calendar API is enabled in your Google Cloud project

License

MIT