Google Calendar MCP Server

# 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: ```bash git clone <repository-url> cd gcal-mcp-server ``` 2. Install dependencies: ```bash npm install ``` 3. Set up environment variables: ```bash cp example.env .env ``` 4. Configure your `.env` file: ``` GOOGLE_PUBLIC_API_KEY=your_google_api_key_here CALENDAR_ID=your_calendar_id_here ``` ## Usage Start the MCP server: ```bash 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