🤖 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:

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

npm install

4. Run the Project

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.