gcal-mcp-server

shaynemeyer/gcal-mcp-server

3.2

If you are the rightful owner of gcal-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Google Calendar MCP Server integrates with the Google Calendar API to allow MCP clients to retrieve calendar events by date.

Tools
1
Resources
0
Prompts
0

Google Calendar MCP Server

A Model Context Protocol (MCP) server that provides integration with Google Calendar API. This server allows MCP clients to retrieve calendar events by date.

Architecture Diagram

┌─────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│   MCP Client    │────▶│  MCP Server         │────▶│  Google Calendar    │
│   (Claude AI,   │     │  (gcal-mcp-server)  │     │      API v3         │
│   other AI      │     │                     │     │                     │
│   assistants)   │     │  ┌──────────────┐   │     │  ┌──────────────┐   │
└─────────────────┘     │  │    Tool:     │   │     │  │   Calendar   │   │
                        │  │getMyCalendar │   │     │  │    Events    │   │
         │              │  │DataByDate    │   │     │  │              │   │
         │              │  └──────────────┘   │     │  └──────────────┘   │
         │              │                     │     │                     │
         │              │  ┌──────────────┐   │     └─────────────────────┘
         │              │  │   Validation │   │                │
         │              │  │    (Zod)     │   │                │
         │              │  └──────────────┘   │                │
         │              │                     │                │
         │              │  ┌──────────────┐   │                │
         │              │  │   Transport  │   │                │
         │              │  │   (stdio)    │   │                │
         │              │  └──────────────┘   │                │
         │              └─────────────────────┘                │
         │                                                     │
         │              Environment Variables:                 │
         │              • GOOGLE_PUBLIC_API_KEY ──────────────┘
         │              • CALENDAR_ID
         │
         └─── Tool Call: getMyCalendarDataByDate(date)
              Returns: { meetings: [...] } or { error: "..." }

Data Flow

  1. MCP Client sends a tool call request to the server via stdio transport
  2. MCP Server receives and validates the request using Zod schema
  3. Tool Function processes the date parameter and makes API call to Google Calendar
  4. Google Calendar API returns events for the specified date range
  5. Server formats the response and sends it back to the client
  6. Client receives structured calendar data or error information

Features

  • Retrieve calendar events for a specific date
  • Integration with Google Calendar API v3
  • Simple MCP tool interface with date validation
  • Error handling for API failures

Prerequisites

  • Node.js (ES modules support required)
  • Google Calendar API access
  • Google API key with Calendar API enabled
  • Target Google Calendar ID

Installation

  1. Clone the repository:
git clone <repository-url>
cd gcal-mcp-server
  1. Install dependencies:
npm install
  1. Set up environment variables:
cp example.env .env
  1. Configure your .env file:
GOOGLE_PUBLIC_API_KEY=your_google_api_key_here
CALENDAR_ID=your_calendar_id_here

Usage

Start the MCP server:

npm start

The server will run using stdio transport and register the following tool:

getMyCalendarDataByDate

Retrieves calendar events for a specified date.

Parameters:

  • date (string): A valid date string (e.g., "2024-01-15", "2024-01-15T10:00:00Z")

Returns:

  • meetings: Array of formatted meeting strings with summary and start time
  • error: Error message if the API call fails

Development

This project uses ES modules and requires Node.js with module support.

Project Structure:

  • server.js - Main MCP server implementation
  • package.json - Project configuration and dependencies
  • example.env - Environment variable template
  • .env - Your local environment configuration (git-ignored)

Dependencies

  • @modelcontextprotocol/sdk - MCP framework
  • googleapis - Google APIs client library
  • dotenv - Environment variable loading
  • zod - Input validation

License

MIT