ai-calendar-assistant

AI Calendar Assistant is a local, privacy-first MCP server that exposes calendar-related tools and lets you chat with your Google Calendar through a local LLM (Ollama). The server runs a calendar MCP server implemented in Python and communicates with the Ollama/MCP client to parse natural language and call the appropriate tools such as listing events, creating events, updating events, and checking availability. You can interact with it via the MCP client (ollmcp) or via Claude Desktop integration, allowing natural language queries like “What’s on my calendar today?” or “Create a meeting tomorrow at 3pm.” The 7 exposed tools include list_events, get_today_events, create_event, search_events, update_event, delete_event, and check_availability, each performing corresponding Google Calendar operations through OAuth2 credentials. When you ask to perform an action, the LLM decides which tool to invoke, the MCP server runs the calendar operation, and the response is returned as a natural-language reply.

To use it, start the MCP client with your servers.json pointing at this Python-based MCP server, and ensure Ollama is running with the llama3.2 model. Then interact using plain language queries; the system will coordinate between the Ollama model, the MCP client, and the calendar tools to produce a concise, actionable response.

Prerequisites:

• Python 3.8+
• Google account with Google Calendar API access enabled
• Ollama installed and running (for local LLM inference)
• Git installed

Installation steps:

1. Clone the repository and install Python dependencies

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

2. Obtain Google Calendar credentials

• Create a project in Google Cloud Console
• Enable Google Calendar API
• Create OAuth 2.0 credentials (Desktop app)
• Download credentials.json and place it in the project root

3. Ensure Ollama is running and the model is pulled

# Start Ollama service (in a separate terminal)
ollama serve

# Pull the Llama 3.2 model (already suggested in docs)
ollama pull llama3.2:3b

4. Run the MCP calendar server

# In this directory
python run_calendar_server.py

5. Start the MCP client configured to connect to this server

ollmcp --servers-json ollmcp_config.json --model llama3.2:3b

Note: If you plan to use Claude Desktop integration, configure the mcpServers as shown in the README example.

Tips and common issues:

• Ensure credentials.json is reachable and has the correct OAuth scopes for Google Calendar access.
• The MCP server runs locally; firewall or network restrictions may block the MCP client from contacting the server. Use localhost and correct port mappings if customized.
• If the Ollama model fails to initialize or times out, verify Ollama is running and that the model llama3.2:3b is downloaded.
• For Claude Desktop integration, follow the optional Claude config snippet in the README, updating the working directory path to your local clone of ai-calendar-assistant.
• Environment variables (such as GOOGLe credentials or calendar scopes) may be required if you customize OAuth flows; keep credentials secure and do not commit secrets.
• The tooling relies on OAuth2; on first run, you may be prompted to authenticate through a browser to grant calendar access.
• If you modify run_calendar_server.py, ensure the MCP protocol exposure remains compatible with the ollmcp client.