🗓️ AI Calendar Assistant

Personal calendar management powered by local LLM (Ollama), Google Calendar API, and Model Context Protocol (MCP)

A lightweight, privacy-first AI calendar assistant that runs entirely on your local machine. Chat with your calendar using natural language, powered by Llama 3.2 running locally via Ollama - completely free, no API costs.

---

✨ Features

• 🤖 Local AI - Uses Ollama (llama3.2:3b) running on your machine
• 📅 Google Calendar Integration - Full read/write access via OAuth2
• 💬 Natural Language - Ask questions in plain English
• ⚡ Fast - Responses in 1-2 seconds
• 🔒 Privacy-First - LLM runs locally, only calendar sync requires internet
• 🆓 100% Free - No API costs, no subscriptions
• 🔌 MCP Compatible - Integrates with Claude Desktop and other MCP clients
• 🎨 Beautiful CLI - Rich terminal interface with color and formatting

---

🏗️ Architecture

┌────────────────────────────────────────────────────────────────┐
│                     MCP Client for Ollama (ollmcp)             │
│               Terminal UI - Natural Language Interface          │
└─────────────────┬──────────────────────┬───────────────────────┘
                  │                      │
                  │ (MCP Protocol)       │ (Ollama API)
                  │                      │
                  ▼                      ▼
┌──────────────────────────────┐  ┌────────────────────────────┐
│   Calendar MCP Server        │  │   Ollama                   │
│   (calendar_server.py)       │  │   Llama 3.2 3B             │
│                              │  │   (Local LLM)              │
│   Exposes 7 Calendar Tools:  │  │                            │
│   • list_events              │  │   Handles:                 │
│   • get_today_events         │  │   • Intent parsing         │
│   • create_event             │  │   • Natural language       │
│   • search_events            │  │   • Response generation    │
│   • update_event             │  │   • Tool orchestration     │
│   • delete_event             │  │                            │
│   • check_availability       │  │                            │
└─────────────┬────────────────┘  └────────────────────────────┘
              │
              │ (Google Calendar API)
              │
              ▼
┌──────────────────────────────┐
│   GoogleCalendarClient       │
│   • OAuth2 Authentication    │
│   • Event CRUD Operations    │
└─────────────┬────────────────┘
              │
              ▼
┌──────────────────────────────┐
│      Google Calendar         │
│      (Cloud Storage)         │
└──────────────────────────────┘

Flow:

1. You type natural language → MCP Client (ollmcp)
2. Ollama (Llama 3.2) understands intent and determines which MCP tools to call
3. MCP Client calls appropriate calendar tools via MCP protocol
4. Calendar MCP Server executes Google Calendar operations
5. Response flows back through MCP → Ollama → formatted natural language response

---

🚀 Quick Start

Prerequisites

• Python 3.8+
• macOS, Linux, or Windows
• Google account
• 4GB RAM (for local LLM)

Installation

1. Install Ollama

   # macOS
   brew install ollama
   
   # Start Ollama service
   ollama serve
   
   # Pull the model (in a new terminal)
   ollama pull llama3.2:3b
   

2. Clone & Setup

   git clone https://github.com/othmane-zizi-pro/ai-calendar-assistant.git
   cd ai-calendar-assistant
   pip install -r requirements.txt
   

3. Get Google Calendar Credentials

   • Go to Google Cloud Console
   • Create a new project
   • Enable "Google Calendar API"
   • Create OAuth 2.0 credentials (Desktop app)
   • Download JSON and save as credentials.json
   • See detailed setup guide

4. Install MCP Client for Ollama

   pip install mcp-client-for-ollama
   

5. Run - Start Natural Language Calendar Chat

   # First run - authenticate with Google (this will open browser)
   python run_calendar_server.py  # Test server once, then Ctrl+C
   
   # Start interactive MCP chat with Ollama
   ollmcp --servers-json ollmcp_config.json --model llama3.2:3b
   

---

💡 Usage

Interactive MCP-Powered Chat

# Start the MCP client with Ollama
ollmcp --servers-json ollmcp_config.json --model llama3.2:3b

Example conversation:

You: What's on my calendar today?
AI: Let me check your calendar for today...
    [Calls get_today_events tool via MCP]

    You have 3 events scheduled today:
    1. Team Standup at 9:00 AM
    2. Client Meeting at 2:00 PM
    3. Gym Session at 6:00 PM

You: Create a meeting tomorrow at 3pm for 1 hour called "Project Review"
AI: I'll create that event for you...
    [Calls create_event tool via MCP]

    ✅ Done! Event "Project Review" scheduled for tomorrow 3:00 PM - 4:00 PM

You: Am I free on Friday afternoon?
AI: Let me check your availability...
    [Calls check_availability tool via MCP]

    Yes, you're free after 2:00 PM on Friday!

Available MCP Tools

The calendar MCP server exposes these tools (automatically used by Ollama through the MCP client):

• list_events - Get upcoming calendar events
• get_today_events - Retrieve today's schedule
• create_event - Create new calendar event
• search_events - Search events by keyword
• update_event - Modify existing event
• delete_event - Remove event from calendar
• check_availability - Check if time slot is free

Alternative: Use with Claude Desktop

If you prefer using Claude Desktop instead of the local Ollama setup:

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "calendar": {
      "command": "python3",
      "args": ["run_calendar_server.py"],
      "cwd": "/path/to/ai-calendar-assistant"
    }
  }
}

Restart Claude Desktop - now Claude can access your calendar via MCP!

---

🛠️ Technical Stack

Core Technologies

Component	Technology	Purpose
MCP Client	mcp-client-for-ollama (ollmcp)	Bridges Ollama with MCP servers, terminal UI
Local LLM	Ollama (Llama 3.2 3B)	Natural language understanding, intent parsing, tool orchestration
MCP Server	Model Context Protocol SDK	Exposes calendar tools via MCP protocol
Calendar API	Google Calendar API v3	Event management, OAuth2 authentication
NLP	LangChain	Prompt engineering, chain-of-thought

Key Features Implementation

1. MCP Server - Tool Exposure

# Expose calendar tools via MCP protocol
@app.list_tools()
async def list_tools():
    return [
        Tool(name="list_events", description="List upcoming calendar events", ...),
        Tool(name="create_event", description="Create a new calendar event", ...),
        Tool(name="search_events", description="Search events by keyword", ...),
        Tool(name="get_today_events", ...),
        Tool(name="update_event", ...),
        Tool(name="delete_event", ...),
        Tool(name="check_availability", ...)
    ]

@app.call_tool()
async def call_tool(name: str, arguments: Any):
    client = get_calendar_client()
    if name == "list_events":
        events = client.list_events(...)
        return [TextContent(type="text", text=formatted_output)]

2. OAuth2 Authentication

# Google Calendar OAuth2 flow
flow = InstalledAppFlow.from_client_secrets_file(
    'credentials.json',
    SCOPES=['https://www.googleapis.com/auth/calendar']
)
creds = flow.run_local_server(port=0)

3. MCP + Ollama Integration

# ollmcp connects Ollama to MCP servers
ollmcp --servers-json ollmcp_config.json --model llama3.2:3b

# User types: "What's on my calendar today?"
# → Ollama (Llama 3.2) understands intent
# → Calls get_today_events tool via MCP protocol
# → Calendar server executes Google Calendar API call
# → Response formatted and returned via MCP
# → Ollama generates natural language response

---

📊 Performance

Metric	Value
Response Time	1-2 seconds (local LLM)
Memory Usage	~4GB RAM (Llama 3.2 3B)
API Calls	Only for calendar sync (free tier: 1M requests/day)
Offline Capability	LLM works offline, calendar requires internet
Cost	$0/month (100% free)

Model Comparison

Model	Size	RAM	Speed	Quality	Use Case
llama3.2:3b	2GB	4GB	⚡⚡⚡	⭐⭐⭐⭐	Recommended
gemma:2b	1.4GB	3GB	⚡⚡⚡⚡	⭐⭐⭐	Faster, lower RAM
phi3:mini	2.3GB	4GB	⚡⚡⚡	⭐⭐⭐⭐	Better code understanding
mistral:7b	4.1GB	8GB	⚡⚡	⭐⭐⭐⭐⭐	Highest quality

---

🔧 Project Structure

ai-calendar-assistant/
├── calendar_assistant/
│   ├── mcp_server/
│   │   ├── __init__.py
│   │   └── calendar_server.py      # MCP server implementation
│   ├── llm/
│   │   ├── __init__.py
│   │   └── local_assistant.py      # Ollama integration
│   ├── utils/
│   │   ├── __init__.py
│   │   └── google_calendar.py      # Google Calendar API wrapper
│   ├── __init__.py
│   └── cli.py                      # CLI interface
├── calendar_assistant.py            # Main entry point
├── requirements.txt                 # Dependencies
├── verify_setup.py                  # Setup verification script
├── .env.example                     # Environment configuration template
├── .gitignore                       # Git ignore rules
├── README.md                        # This file
├── QUICKSTART.md                    # 5-minute setup guide
├── SETUP.md                         # Detailed setup instructions
└── LOCAL_LLM_SETUP.md              # Ollama installation guide

---

🎯 MCP Tools Available

When integrated with Claude Desktop, the following tools are exposed:

Tool	Description	Parameters
list_events	Get upcoming calendar events	max_results, days_ahead
get_today_events	Retrieve today's schedule	None
create_event	Create a new calendar event	summary, start_time, end_time, description, location
search_events	Search events by keyword	query, max_results
update_event	Modify existing event	event_id, summary, start_time, end_time
delete_event	Remove event from calendar	event_id
check_availability	Check if time slot is free	start_time, end_time

---

🔐 Privacy & Security

• ✅ Local LLM - All AI processing happens on your machine
• ✅ OAuth2 - Secure Google authentication
• ✅ No Cloud LLM APIs - No data sent to OpenAI/Anthropic
• ✅ Credentials Protected - credentials.json and token.pickle in .gitignore
• ✅ Open Source - Full transparency, audit the code yourself

Data Flow:

1. Your query → Local LLM (Ollama) → Intent extracted
2. Calendar operation → Google Calendar API (OAuth2)
3. Response → Local LLM → Natural language response

---

📚 Documentation

• Quick Start Guide - Get running in 5 minutes
• Setup Guide - Detailed installation instructions
• Local LLM Setup - Ollama configuration

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📝 License

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

---

🙏 Acknowledgments

• Ollama - Local LLM runtime
• Model Context Protocol - AI integration framework
• Google Calendar API - Calendar integration
• LangChain - LLM orchestration
• Rich - Beautiful terminal output

---

📧 Contact

Othmane Zizi - othmane.zizi.pro@gmail.com

Project Link: https://github.com/othmane-zizi-pro/ai-calendar-assistant

---

⭐ Star this repo if you found it helpful!