This repo demonstrates how to build a telegram bot using SSE Server and implement agentic flow using MCP with tools like Gmail, GDrive
Documentation
Quirox Telegram Bot Backend
This project provides the backend services for the Quirox Telegram Bot, featuring an AI agent capable of interacting with various tools like Google Sheets, Gmail (currently commented out), and web search via DuckDuckGo. It uses the Model Context Protocol (MCP) to manage communication between the AI model (Google Gemini) and the available tools. The backend is exposed via a FastAPI web server.
Demo
Features
- AI Agent: Uses Google Gemini (Flash model) for reasoning and task execution.
- Tool Integration:
- Google Sheets: Create spreadsheets, read/write data, manage sheets (list, copy, rename), share. Uses
helpers/ghseet.py(viaGoogleSheetsService). - Web Search: Search the web using DuckDuckGo (
helpers/search_tools.py). - Web Content Fetching: Fetch and parse text content from URLs (
helpers/search_tools.py). - (Experimental/Disabled) Gmail: Functions for sending, reading, and managing emails are present in
helpers/gmail_tools.pybut appear commented out inmcp_server.py. - MCP Framework:
-
mcp_server.py: Runs the MCP server, exposing tools (Sheets, Search, Fetch) to the AI model. -
mcp_client.py: Communicates with the MCP server, sends user queries to the Gemini model, handles tool calls, and manages the conversation flow. - FastAPI Interface:
-
main.py: Starts a FastAPI web server, providing a/chatendpoint to interact with the AI agent via HTTP requests.
Project Structure
├── README.md # This file
├── .env # Environment variables (API keys, paths) - MUST BE CREATED
├── .gitignore # Git ignore patterns
├── requirements.txt # Python dependencies
├── main.py # FastAPI application entry point
├── mcp_client.py # MCP client logic interacting with Gemini and MCP Server
├── mcp_server.py # MCP server exposing tools
├── helpers/ # Directory for helper modules and tools
│ ├── config.py # Loads Gemini API key
│ ├── gsheet_tools.py # (Potentially older) MCP tool definitions for Google Sheets
│ ├── ghseet.py # Standalone GoogleSheetsService class
│ ├── gmail_tools.py # Gmail service class and MCP tool definitions (currently unused)
│ ├── search_tools.py # DuckDuckGo search and Web Content Fetcher classes
│ └── init.py
├── telegram_bot/ # (Empty/Placeholder?) Directory for Telegram bot specific code
└── bot/ # (Empty/Placeholder?) Another potential bot directory
## Setup
### 1. Prerequisites
* Python 3.8+
* Access to Google Cloud Platform for Sheets/Drive API and potentially Gmail API.
* Google Gemini API Key.
### 2. Clone the Repositorygit clone
cd
### 3. Install Dependenciespip install -r requirements.txt
### 4. Environment Variables
Create a `.env` file in the root directory by copying `.env.example` (if it existed) or creating it from scratch. Add the following variables:Google Gemini API Key
GEMINI_API_KEY=your_gemini_api_key
Google Cloud Credentials (Choose ONE method: Service Account or OAuth)
Method 1: Service Account (Recommended for servers)
Path to your service account JSON key file
SERVICE_ACCOUNT_PATH=path/to/your/service_account.json
Optional: Google Drive Folder ID to work within
DRIVE_FOLDER_ID=your_google_drive_folder_id
Method 2: OAuth 2.0 (Requires user interaction for the first run)
Path to your OAuth client secrets file (credentials.json)
CREDENTIALS_PATH=path/to/your/credentials.json
Path where the OAuth token will be stored after authorization
TOKEN_PATH=token.json # Keep default unless you have a reason to change
Method 3: Base64 Encoded Service Account Config (Alternative)
CREDENTIALS_CONFIG=your_base64_encoded_service_account_json_string
**Important:**
* Ensure the Google Sheets API and Google Drive API are enabled in your Google Cloud project.
* If using OAuth (`CREDENTIALS_PATH`), the first time `mcp_server.py` (or code using `GoogleSheetsService`/`GmailService`) runs, it will open a browser window for you to authorize the application. The resulting `token.json` will be saved.
* If using a Service Account (`SERVICE_ACCOUNT_PATH`), ensure the service account email has been granted appropriate permissions (e.g., Editor) on the target Google Sheets or Drive Folder.
### 5. Google Cloud Authentication Setup
* **Service Account:**
1. Go to the Google Cloud Console -> IAM & Admin -> Service Accounts.
2. Create a service account or use an existing one.
3. Create a key (JSON format) for the service account and download it.
4. Set `SERVICE_ACCOUNT_PATH` in `.env` to the path of the downloaded JSON file.
5. Share any specific Google Drive folders or Sheets with the service account's email address.
* **OAuth 2.0:**
1. Go to Google Cloud Console -> APIs & Services -> Credentials.
2. Create "OAuth 2.0 Client ID" of type "Desktop app".
3. Download the client secrets JSON file.
4. Rename it to `credentials.json` (or update `CREDENTIALS_PATH` in `.env`).
## Usage
The application consists of two main parts that need to run concurrently: the MCP Server and the FastAPI frontend (which uses the MCP Client).
### 1. Run the MCP Server
This server provides the tools (Sheets, Search) to the AI.python mcp_server.py
Keep this terminal window open.
### 2. Run the FastAPI Application
This starts the web server that listens for chat requests.python main.py
or using uvicorn directly for more options:
uvicorn main:app --reload --host 0.0.0.0 --port 8000
### 3. Interact via API
You can now send POST requests to the `/chat` endpoint:
**Example using `curl`:**curl -X POST "http://localhost:8000/chat" \
-H "Content-Type: application/json" \
-d '{"message": "Create an excel sheet named '\''Test Sheet'\'' and add the headers Name, Age, City in the first row."}'
The response will contain the final answer generated by the AI after potentially interacting with the tools via the MCP server.
## Key Modules (`helpers/`)
* `config.py`: Loads the `GEMINI_API_KEY` from the environment.
* `search_tools.py`: Contains `DuckDuckGoSearcher` for web searches and `WebContentFetcher` for retrieving content from URLs. Includes rate limiting.
* `ghseet.py`: Implements `GoogleSheetsService` providing a class-based interface to Google Sheets and Drive APIs (Create, Read, Update, Batch Update, Add Rows/Cols, List Sheets, Share, etc.). Handles authentication internally.
* `gmail_tools.py`: Implements `GmailService` (similar structure to `GoogleSheetsService`) for Gmail operations. Contains MCP tool definitions for email tasks, though currently seems disabled in the `mcp_server.py`.
* `gsheet_tools.py`: Contains older, function-based MCP tool definitions for Google Sheets, likely superseded by `ghseet.py`.
## Dependencies
Key dependencies include:
* `fastapi`, `uvicorn`: For the web server.
* `mcp`: Model Context Protocol library.
* `google-api-python-client`, `google-auth-oauthlib`, `google-auth`: Google API libraries.
* `google-generativeai`: Google Gemini client library.
* `python-dotenv`: For loading environment variables.
* `httpx`, `beautifulsoup4`: For web search and content fetching.
* `rich`: For formatted console output.
See `requirements.txt` for the full list.Similar MCP
Based on tags & features
Trending MCP
Most active this week