mcp google calendar

A Model Context Protocol (MCP) server that integrates with Google Calendar, built with TypeScript.

Features

• Seamless Google Calendar integration with OAuth 2.0 authentication
• Persistent token storage for automatic authentication
• List and manage calendars with comprehensive event operations
• Create, read, update, and delete calendar events
• Fetch calendar events between specified dates
• Server-Sent Events (SSE) transport option for real-time updates
• Simple integration with Claude and other MCP-compatible AI assistants

Installation

npm install -g mcp-google-calendar

Or run directly with:

npx -y mcp-google-calendar

Prerequisites

1. Node.js (v16 or higher)
2. Google Cloud Platform account
3. Google Calendar API enabled
4. OAuth 2.0 credentials

Setup

1. Google Cloud Configuration

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Calendar API:
4. Navigate to "APIs & Services" > "Library"
5. Search for "Google Calendar API"
6. Click "Enable"
7. Configure OAuth consent screen:
8. Go to "APIs & Services" > "OAuth consent screen"
9. Choose "External" user type (or "Internal" for Google Workspace)
10. Fill in required information:
    • App name: mcp-calendar
    • User support email: (your email)
    • Developer contact information: (your email)
11. Add scopes:
    • Click "Add or Remove Scopes"
    • Find and select "https://www.googleapis.com/auth/calendar.events"
    • Add your email as a test user
12. Complete the setup
13. Create OAuth credentials:
14. Go to "Credentials"
15. Click "Create Credentials" > "OAuth Client ID"
16. Choose "Desktop app" as application type
17. Name it (e.g., "MCP Calendar Desktop Client")
18. Download the JSON file and save as credentials.json in your project directory

2. Environment Configuration

Create a .env file in your project root:

# Server configuration
PORT=3420

# Google Calendar API configuration
CREDENTIALS_PATH=./credentials.json

Usage

Starting the Server

Start with standard WebSockets:

npx -y mcp-google-calendar

Start with Server-Sent Events (SSE):

npx -y mcp-google-calendar --sse

With Claude Desktop

Add this to your claude_desktop_config.json:

{
   "mcpServers": {
      "mcp-google-calendar": {
         "command": "npx",
         "args": ["-y", "mcp-google-calendar"],
         "env": {
            "CREDENTIALS_PATH": "/path/to/your/credentials.json"
         }
      }
   }
}

Authentication Process

The first time you run the server: 1. A browser window will open automatically 2. Sign in with your Google account 3. Grant the requested calendar permissions 4. The authentication token is saved to token.json

On subsequent launches: - The server uses the saved token automatically - No browser interaction is required unless the token expires

Available Tools

Development

Clone and set up the project:

git clone https://github.com/am2rican5/mcp-google-calendar.git
cd mcp-google-calendar
npm install

Build the project:

npm run build

Run in development mode:

npm start

Security Considerations

⚠️ Important Security Warning ⚠️

• credentials.json and token.json contain sensitive authentication information
• Never commit these files to version control or share them publicly
• Each user should create their own OAuth credentials
• If you suspect credential compromise, revoke them immediately in Google Cloud Console
• The token grants access to your Google Calendar data

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request