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

Related MCP server: mcp-google-calendar

🏗️ Tech Stack

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

🚀 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.