Telegram Reminder MCP

A context-aware, secure, and intuitive Telegram Reminder Bot powered by FastMCP and SQLite3. Set, view, modify, and delete reminders using simple conversational phrases or standard commands.

🤖 Live Bot & Web Preview

• Telegram Bot: Reminder_MCP_Bot
• Web Dashboard: reminder.minecraftbedrock.dpdns.org

---

✨ Features

1. Natural Language Parsing: Recognizes relative phrases to set reminders (e.g., in 5 minutes, after 2 hours, in 3 days).
2. Full CRUD Capabilities: View, update, or cancel your reminders directly from Telegram chat messages.
3. Strict Privacy & Multi-User Isolation: Reminders are strictly isolated using Telegram chat_id. A user can never view, edit, or delete reminders belonging to another Telegram user.
4. Local Timezone Alignment: Configured specifically to calculate and store times in the Asia/Kolkata (IST) timezone.
5. Robust Cron Engine: A background worker polls the database every 5 seconds to ensure alerts are dispatched down to the second.
6. Voice Message Support & Normalization: Send voice notes directly in Telegram to set, list, edit, or delete reminders. Spoken number words (like "five" or "twenty-three") are automatically normalized to digits (like "5" or "23") to integrate seamlessly with the command parser.

---

💬 Sentence Tips & Parser Syntax

The bot supports natural conversational inputs. The syntax parser uses flexible regular expressions under the hood.

Setting a Reminder

You can set reminders using two main sentence structures:

• remind me after [number] [unit] to [action]
  • Example: remind me after 15 minutes to drink water
  • Example: remind me after 1 hr to stretch
• remind me to [action] in [number] [unit]
  • Example: remind me to call dad in 2 days
  • Example: remind me to stretch in 30 seconds

Supported Units: sec, second, seconds, min, minute, minutes, hr, hour, hours, day, days.

Voice Message Commands

You can tap the microphone icon in Telegram to speak any command. Spoken numbers are converted to digits automatically:

• Voice Input: "remind me in ten minutes to do yoga" -> bot normalizes to "remind me in 10 minutes to do yoga" and schedules it.
• Voice Input: "list reminders" -> bot transcribes and returns active reminders.
• Voice Input: "delete reminder four" -> bot normalizes to "delete reminder 4" and deletes it.
• Voice Input: "edit reminder five to walk dog in twenty minutes" -> bot normalizes to "edit reminder 5 to walk dog in 20 minutes" and updates it.

Updating a Reminder via Chat

• edit reminder [id] to [new text] or edit [id] to [new text]
  • Example: edit reminder 11 to go to gym in 5 minutes
  • Example: edit 11 to buy juice

Deleting a Reminder via Chat

• delete reminder [id], delete [id], or remove [id]
  • Example: delete reminder 11

Listing Reminders via Chat

• list reminders, list, list all, or show reminders

---

🛠️ Command Reference

For users who prefer classic bot commands:

Command	Usage	Description
/start	/start	Welcomes the user and lists available options.
/help	/help	Displays the usage guidelines and tips.
/list	/list	Displays a detailed list of all your active reminders and their remaining time.
/delete	/delete <id>	Instantly cancels and removes the specified reminder from the database.
/edit	/edit <id> <new text and/or time>	Modifies the task text or time offset for an active reminder.

---

🔒 Security & Multi-User Privacy Check

All reminder actions (reading, updating, deleting) are secured on the FastMCP Server by verifying that the requesting user's Telegram chat_id matches the owner of the target reminder ID in the database.

• Isolation Test: If User A attempts to run delete reminder 5 or /delete 5, but the reminder belongs to User B, the server returns an Unauthorized error and blocks the transaction.
• Result: Reminders are strictly confidential, and no cross-user visibility is possible.

---

🚀 Technical Setup (Local Deployment)

1. Requirements

• Python 3.9+
• FastMCP
• SQLite3

2. Configuration

Copy the .env.template to .env and fill in your details:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token
MCP_SERVER_URL=http://127.0.0.1:9876/mcp

3. Run Server

Start the database server:

python3 server.py

4. Run Client

Start the Telegram Bot polling and background cron checker:

python3 client.py