AI Calendar Assistant

🗓️ AI日历助手

个人日历管理由 本地法学硕士 （奥拉马）， 谷歌日历API，以及 模型上下文协议（MCP）

   

一个轻量级的、隐私优先的AI日历助手，完全在您的本地机器上运行。使用自然语言与日历聊天，由 Llama 3.2 通过本地运行 奥拉马 -完全免费，无API费用。

______________________________________________________________________

✨ 特性

• 🤖 本地AI -使用在您的机器上运行的Ollama（骆驼3.2:3b）
• 📅 谷歌日历集成 -通过OAuth2进行完全读/写访问
• 💬 自然语言 -用简单的英语提问
• ⚡ 快速 -1-2秒内响应
• 🔒 隐私第一 -LLM在本地运行，只有日历同步需要互联网
• 🆓 100%免费 -无API成本，无订阅
• 🔌 MCP兼容 -与Claude Desktop和其他MCP客户端集成
• 🎨 漂亮的CLI -丰富的终端界面，具有颜色和格式

______________________________________________________________________

🏗️ 建筑

┌────────────────────────────────────────────────────────────────┐
│                     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)         │
└──────────────────────────────┘

流量：

1. 您键入自然语言→ MCP客户端（ollmcp）
2. Ollama（Llama 3.2）理解意图并确定调用哪些MCP工具
3. MCP客户端通过MCP协议调用相应的日历工具
4. 日历MCP服务器执行谷歌日历操作
5. 响应通过MCP返回→ 奥拉玛→ 格式化自然语言响应

______________________________________________________________________

🚀 快速开始

先决条件

• Python 3.8+
• macOS、Linux或Windows
• Google账户
• 4GB RAM（用于本地LLM）

安装

1. 安装Ollama

   # macOS
   brew install ollama

   # Start Ollama service
   ollama serve

   # Pull the model (in a new terminal)
   ollama pull llama3.2:3b

1. 克隆和设置

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

1. 获取谷歌日历凭据

- 首选 谷歌云控制台 - 创建一个新项目 - 启用“Google日历API” - 创建OAuth 2.0凭据（桌面应用程序） - 下载JSON并另存为 credentials.json - 看 详细设置指南

1. 为Ollama安装MCP客户端

   pip install mcp-client-for-ollama

1. 运行-开始自然语言日历聊天

   # 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

______________________________________________________________________

💡 用法

交互式MCP驱动聊天

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

对话示例：

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!

可用的MCP工具

日历MCP服务器公开了这些工具（Ollama通过MCP客户端自动使用）：

• list_事件 -获取即将到来的日历活动
• get_today_events -检索今天的日程安排
• create_event -创建新日历事件
• 搜索事件 -按关键字搜索事件
• update_事件 -修改现有事件
• 删除事件 -从日历中删除事件
• check_可用性 -检查时隙是否空闲

替代方案：与Claude Desktop一起使用

如果您更喜欢使用Claude Desktop而不是本地Ollama设置：

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

重新启动克劳德桌面-现在克劳德可以通过MCP访问您的日历！

______________________________________________________________________

🛠️ 技术栈

核心技术

关键功能实现

1. MCP服务器-工具曝光

# 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身份验证

# 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集成

# 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

______________________________________________________________________

📊 演出

模型比较

______________________________________________________________________

🔧 项目结构

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工具可用

当与Claude Desktop集成时，将公开以下工具：

______________________________________________________________________

🔐 隐私和安全

• ✅ 本地法学硕士 -所有AI处理都在您的机器上进行
• ✅ OAuth2 -安全的Google身份验证
• ✅ 没有云LLM API -没有数据发送到OpenAI/Anthropic
• ✅ 凭据受保护 - credentials.json 和 token.pickle 在 .gitignore
• ✅ 开源 -完全透明，自己审核代码

数据流：

1. 您的查询→ 当地法学硕士（Ollama）→ 提取意图
2. 日历操作→ Google日历API（OAuth2）
3. 响应→ 本地法学硕士→ 自然语言响应

______________________________________________________________________

📚 文档

• 快速入门指南 -5分钟后开始跑步
• 安装指南 -详细的安装说明
• 本地LLM设置 -Ollama配置

______________________________________________________________________

🤝 贡献

欢迎投稿！请随时提交拉取请求。

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/AmazingFeature)
3. 提交您的更改(git commit -m 'Add some AmazingFeature')
4. 推到分支(git push origin feature/AmazingFeature)
5. 打开拉取请求

______________________________________________________________________

📝 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

🙏 致谢

• 奥拉马 -本地LLM运行时
• 模型上下文协议 -人工智能集成框架
• 谷歌日历API -日历集成
• LangChain -LLM编排
• 富有的 -漂亮的终端输出

______________________________________________________________________

📧 联系

奥斯曼·齐齐 - othmane.zizi.pro@gmail.com

项目链接：

______________________________________________________________________

⭐ 如果你觉得这个repo有用，请将其标记为星号！