Telegram Bot with MCP Tools

This repository contains a Telegram chatbot that can interact with an AI agent and use external tools through the Model Context Protocol (MCP). The project is currently in an early production stage and is being developed as a basic but functional prototype.

Overview

The project combines:

• A Telegram bot interface

• An AI agent powered by OpenAI Agents

• An MCP server exposing tools to the agent

• Tool integrations for calendar events, reminders, and CSV file summaries

The goal is to let users chat with the bot in Telegram and ask it to perform actions such as creating calendar events or scheduling reminders.

Current Status

This project is still under active development and is currently very basic. The core flow works, but the implementation is intentionally simple and may evolve as more tools and features are added.

Main Features

Telegram integration

• Receives plain text messages from Telegram users

• Sends responses back to the user

• Uses the AI agent to interpret the request

AI agent and MCP

• Uses OpenAI Agents

• Connects to an MCP server through stdio

• Exposes tools that the agent can call dynamically

Available tools

The current tool set includes:

• Calendar integration

  • Create Google Calendar events

• Reminders

  • Schedule reminders for users

  • Background worker checks and sends reminders when due

• Data files

  • Summarize CSV files from the data directory

Project Structure

• main.py: entry point to start the MCP server

• runTelegram.py: entry point to start the Telegram bot

• src/telegram/telegramConnection.py: Telegram bot logic

• src/aiResponse/response.py: AI agent initialization, execution, and shutdown

• src/aiResponse/prompts/systemPrompt.md: system prompt used by the agent

• src/mcp/server/init.py: shared MCP server instance

• src/mcp/tools/: MCP tool implementations

  • calendar_tool.py

  • reminder_tool.py

  • csv_tool.py

• src/functions/: helper modules for integrations

  • calendar/calendar_conection.py

  • reminders/reminders.py

  • datafiles/readFile.py

Technologies Used

• Python 3.12+

• python-telegram-bot

• OpenAI Agents SDK

• MCP (Model Context Protocol)

• Google Calendar API

• pandas

• pyarrow

Dependencies

The project dependencies are defined in pyproject.toml. The main ones include:

• google-api-python-client

• google-auth

• google-auth-oauthlib

• mcp[cli]

• openai

• openai-agents

• pandas

• pyarrow

• python-telegram-bot

Environment Variables

The application expects the following environment variables:

• TELEGRAM_BOT_TOKEN: token for the Telegram bot

• OPENAI_MODEL_NAME: model name to use with OpenAI Agents

• MCP_PATH: module path for the MCP server entry point

You can define them in a .env file or export them in your shell.

Setup

1. Clone the repository.

2. Create and activate a virtual environment.

3. Install dependencies:

   pip install -e .

4. Create a .env file with the required environment variables.

5. Make sure the required credentials are available:

   • Telegram bot token

   • OpenAI model access

   • Google Calendar credentials if you want calendar features

Running the Project

Start the MCP server:

python main.py

Start the Telegram bot:

python runTelegram.py

Once both are running, you can send messages to the bot in Telegram.

Example Usage

You can try requests such as:

• "Create a calendar event for tomorrow at 10:00"

• "Schedule a reminder for me at 8 PM"

• "Summarize the CSV file in the data folder"

Notes

• The repository includes some sample data files under src/functions/datafiles/.

• Reminder scheduling uses a local SQLite database file named reminders.db.

• Calendar integration uses a stored Google credentials file named token.pickle.

• The current implementation is intentionally minimal and serves as a starting point for expanding the bot with more tools and capabilities.

License

This project is distributed under the MIT License. See the LICENSE file for details.