# šļø Google Calendar MCP Server
This project integrates the **Google Calendar v3 APIs** with a custom **MCP (Model Context Protocol) Server**, enabling natural language interaction with your calendar via tools like **Claude Desktop**.
It acts as a bridge between your calendar data and an LLM using MCP-compatible HTTP streaming.
---
## š§ Overview
This project contains two core servers:
### 1. š Google OAuth Server
- Handles OAuth 2.0 flow
- Stores and refreshes access tokens in a local session file
### 2. š¤ MCP Server
- Implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)
- Exposes an HTTP streaming interface
- Uses saved credentials to interact with [Google Calendar API v3](https://developers.google.com/calendar/api/v3/reference)
---
## š Getting Started
### Step 1: š§ Set Up Google API Credentials
1. Go to the [Google Cloud Console](https://console.cloud.google.com/apis/dashboard)
2. Create or select a project
3. Enable the **Google Calendar API**
4. Go to **Credentials** ā *Create OAuth 2.0 Client ID*
- Choose **Desktop App**
- Set branding and add test user emails in audience
5. Download the OAuth credentials as `client_secret.json`
6. Place this file in the **root directory** of the project
---
### Step 2: š¦ Install Dependencies
```bash
poetry install
````
---
### Step 3: šŖ Start the OAuth Server
```bash
poetry run uvicorn src.main:app --host 0.0.0.0 --port 8000
```
* This should automatically open a browser for OAuth authentication.
* If not, visit [http://0.0.0.0:8000/google\_oauth/](http://0.0.0.0:8000/google_oauth/)
* Upon successful authentication, you'll see a success page.
* A `session.json` file will be created with your access/refresh tokens.
---
### Step 4: š§© Run the MCP Server
```bash
poetry run python src/server.py
```
> This launches a streamable MCP-compatible HTTP server at `http://localhost:8080/mcp`
---
### Step 5: š§ Connect MCP Client (Claude Desktop)
Update the config file at:
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```
Add the following entry:
```json
{
"mcpServers": {
"google-calendar-mcp": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:8080/mcp"
]
}
}
}
```
---
### Step 6: ā
Verify Integration
* Open **Claude Desktop** settings.
* If the MCP server was added correctly, it will appear under *Settings -> integrations*
## š§ Demo
https://github.com/user-attachments/assets/27a8e5ee-8f2f-40c7-bdfc-1caa93767efb
## š§± Project Structure
```plaintext
project-root/
āāā client_secret.json # Google OAuth credentials
āāā session.json # Access/refresh token storage
āāā pyproject.toml # Poetry project config
āāā README.md
āāā src/
āāā main.py # FastAPI app for OAuth server
āāā server.py # MCP-compatible server
āāā settings.py # App settings and constants
āāā api/
ā āāā oauth_callback.py # OAuth endpoint logic
āāā core/
ā āāā calendar_client.py # Google Calendar API wrapper
ā āāā mcp_tools.py # Tools exposed to MCP clients
ā āāā oauth_manager.py # OAuth initiation and flow
ā āāā session_manager.py # Token handling
āāā gcalendar_types/ # Typed definitions for Calendar v3 API
```
---
## š§© Dependencies
* [FastAPI](https://fastapi.tiangolo.com/)
* [Uvicorn](https://www.uvicorn.org/)
* [Google Auth Libraries](https://pypi.org/project/google-auth/)
* [Poetry](https://python-poetry.org/) for dependency management
---
