# 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