[![M8ven Verified](https://m8ven.ai/badge/mcp/taivo1905-google-workspace-mcp-wypeim)](https://m8ven.ai/mcp/taivo1905-google-workspace-mcp-wypeim)
<!-- m8ven-verify: 566143feba6e23f03b3eedbf343484b3 -->

# 🤖 Google Workspace MCP + Telegram AI Agent

A comprehensive learning project focused on exploring and applying modern AI Agent technologies, specifically integrating the **Model Context Protocol (MCP)** with **Google Gemini API** and a **Telegram Bot**.

This project transforms your Telegram into a smart, personal AI Assistant capable of engaging in natural language conversations and directly operating across your entire Google Workspace ecosystem (Gmail, Calendar, Sheets, Docs, Drive).

---

## 🎯 Learning Objectives

This project is meticulously designed to help you practice and understand the following core concepts:
1. **Agentic AI & Tool Calling**: Understanding how a Large Language Model (Gemini) analyzes user intent and autonomously decides to invoke external tools to accomplish complex tasks.
2. **Model Context Protocol (MCP)**: Learning the latest open standard (from Anthropic/Google) that standardizes how AI models connect to external data sources and tools.

---

## 🏗️ Tech Stack

Built with a modern, lightweight, and type-safe technology stack:

| Layer | Technology | Purpose |
|-------|-----------|----------|
| **AI Brain** | Google Gemini (`@google/generative-ai`) | Blazing-fast LLM Engine (gemini-3.1-flash-lite) responsible for Natural Language Understanding and Tool Calling. |
| **Tool Protocol**| MCP SDK v2.0 (`@modelcontextprotocol/server`) | Defining and registering tools adhering to industry-standard protocols. |
| **Chat Interface**| grammY (`grammy`) | A robust Telegram Bot framework secured via an `ALLOWED_USER_IDS` whitelist. |
| **Integrations** | Google APIs (`googleapis`) | Native interaction with Gmail, Calendar, Sheets, Drive, and Docs. |
| **Validation** | Zod (`zod`) | Type-safe schema validation ensuring valid input data for MCP tools. |
| **Runtime** | Node.js + TypeScript (`tsx`) | Executing ES Modules natively without complex build steps. |

---

## 🚀 How It Works (The Concept)

1. **User Request**: You send a message via Telegram (e.g., *"Find my free slots next week and schedule a team sync"*).
2. **Bot Middleware**: The Telegram bot receives the message, validates your identity against the `ALLOWED_USER_IDS` whitelist, and forwards it to the AI Agent.
3. **Multi-Turn Tool Calling Loop**: 
   - Gemini deduces the intent and issues a function call to `get_calendar_events`.
   - The Agent executes the tool via the **MCP Server** registry.
   - The MCP Server authenticates with Google via OAuth tokens and makes the respective **Google API** request.
   - The calendar data is returned to Gemini.
   - Gemini analyzes the data, calls `find_free_slots`, and subsequently calls `create_calendar_event` to book the meeting.
4. **Final Response**: The AI Agent synthesizes the results and sends a final, human-readable response back to you on Telegram.

---

## 📦 13 Built-in MCP Tools

This project abstracts complex Google APIs into 13 LLM-friendly MCP tools:

* **📧 Gmail:** `get_unread_emails`, `search_emails`, `get_email_detail`, `draft_email`, `send_email`.
* **📅 Calendar:** `get_calendar_events`, `find_free_slots`, `create_calendar_event`, `update_calendar_event`.
* **📊 Sheets:** `read_sheet`, `append_sheet_row`.
* **📁 Drive/Docs:** `search_drive_files`, `read_doc_content`.

---

## ⚙️ Setup Instructions

### 1. Prerequisites
- Node.js 20+
- A Google Cloud Project (with Gmail, Calendar, Sheets, Docs, and Drive APIs enabled).
- OAuth 2.0 Client ID (configured as a Desktop Application).
- Telegram Bot Token (obtained from @BotFather).
- Gemini API Key.

### 2. Environment Configuration
Copy the environment template and fill in your details:
```bash
cp .env.example .env
```
Provide your OAuth Client credentials, Bot Token, Gemini API Key, and—most importantly—your **`ALLOWED_USER_IDS`** (your Telegram User ID to prevent unauthorized access).

### 3. Install Dependencies
```bash
npm install
```

### 4. Run the Project
```bash
npm run dev
```
> During the initial startup, the system will open a browser window requesting Google account authorization. Your OAuth credentials will be securely saved locally in `credentials/tokens.json`.

---

## 📜 License
This project was built for educational and personal use. Please keep your `.env` and `tokens.json` files strictly confidential.