READMEmain

Calendar Agent MCP

Python client for Google Calendar MCP server integration.

Overview

This project integrates with the google-calendar-mcp server to provide a seamless Python interface for Google Calendar operations. The architecture follows:

[Python App] <--> [Python MCP Client] <--> [Node.js MCP Server] <--> [Google Calendar API]

Features

List available calendars
List events from a calendar
Create new calendar events
Update existing events
Delete events
Process events from screenshots and images

Project Structure

calendar-agent-mcp/
├── mcp-server/                # External MCP server source (git submodule)
├── mcp_client/                # Python MCP client
│   ├── __init__.py
│   ├── client.py              # MCPClient class
│   ├── connection.py          # MCPConnection class
│   └── models.py              # Data model classes
├── app/                       # Python application
│   ├── __init__.py
│   ├── main.py                # Main application code
│   └── ui.py                  # User interface code
├── tests/                     # Test code
│   ├── __init__.py
│   ├── test_client.py
│   └── test_integration.py
├── README.md                  # Project documentation
├── requirements.txt           # Python dependencies
└── pyproject.toml             # Package configuration

Installation

Prerequisites

Python 3.8 or higher
Node.js 16 or higher
Git

Setup

Clone the repository with submodules:

git clone --recurse-submodules https://github.com/adalgu/calendar-agent-mcp.git
cd calendar-agent-mcp

Install Python dependencies:

# Using pip
pip install -r requirements.txt

# Using uv
uv pip install -r requirements.txt

Set up the MCP server:

cd mcp-server
npm install
npm run build

Configure Google OAuth credentials:

Go to the Google Cloud Console
Create a new project or select an existing one
Enable the Google Calendar API
Create OAuth 2.0 credentials (Desktop app)
Download the credentials and save as gcp-oauth.keys.json in the mcp-server directory

Usage

Basic Example

from mcp_client.client import MCPClient

# Initialize the client with path to MCP server
client = MCPClient(server_path="./mcp-server/build/index.js")

# Connect to the server
client.connect()

# List available calendars
calendars = client.list_calendars()
print(f"Available calendars: {calendars}")

# List events from primary calendar
events = client.list_events("primary")
print(f"Upcoming events: {events}")

# Create a new event
new_event = client.create_event(
    calendar_id="primary",
    summary="Team Meeting",
    start="2025-04-01T10:00:00",
    end="2025-04-01T11:00:00",
    location="Conference Room A",
    attendees=[{"email": "colleague@example.com"}]
)
print(f"Created event: {new_event}")

Authentication

The first time you run the client, it will open a browser window for Google OAuth authentication. Follow the prompts to authorize the application. The authentication tokens will be saved for future use.

Development

Running Tests

python -m unittest discover tests

Building the Package

pip install build
python -m build

License

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

Acknowledgments

This project uses the google-calendar-mcp server, which is a fork of the original nspady/google-calendar-mcp repository.