imvickykumar999/telegram-reminder-mcp repository overview

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

⁠🔒 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