@mcp-registry/mcp-telegram-ai-assistant v1.0.3

MCP Telegram AI Assistant

A professional Model Context Protocol (MCP) server that leverages Google's Gemini AI to provide intelligent responses through Telegram. Perfect for students, educators, researchers, and professionals who need quick, intelligent assistance.

Developer: Falah.G.Salieh (Iraq) © 2025

🎥 Demo

🌟 Key Features

• Intelligent Content Generation: Powered by Google's Gemini AI for high-quality responses
• Real-time Telegram Integration: Instant access to AI capabilities through Telegram
• Multi-language Support: Works with multiple languages including RTL languages (Arabic, etc.)
• Automatic Response Storage: All generated content is saved for future reference
• Professional Output Formatting: Clean, well-formatted responses in both Telegram and saved files

🎯 Benefits for Different Users

For Students

• Quick research assistance
• Help with understanding complex topics
• Study material generation
• Question answering and explanations

For Educators

• Teaching material preparation
• Example generation
• Concept explanations
• Course content organization

For Researchers

• Literature review assistance
• Research summarization
• Hypothesis generation
• Data interpretation help

🚀 Getting Started

Prerequisites

• Node.js (v16 or higher)
• A Telegram Bot Token (from @BotFather)
• Google Gemini API Key

Telegram Bot Setup Guide

1. Create a New Bot:

   • Open Telegram and search for @BotFather
   • Send /newbot command to BotFather
   • Follow the prompts:
     • Enter a display name for your bot
     • Choose a username ending in 'bot' (e.g., 'my_ai_assistant_bot')
   • Save the API token provided by BotFather (looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

2. Get Your Chat ID:

   • Open Telegram and search for @userinfobot
   • Send any message to this bot
   • It will reply with your Chat ID (a number like 123456789)
   • Save this number for your configuration

3. Initialize Your Bot:

   • Search for your new bot using its username
   • Start a chat with your bot
   • Send the /start command
   • Your bot is now ready to receive commands

4. Configure Environment Variables:

   • Create a .env file in your project root
   • Add your bot token and chat ID:

     TELEGRAM_BOT_TOKEN=your_bot_token_here
     TELEGRAM_CHAT_ID=your_chat_id_here
     GEMINI_API_KEY=your_gemini_api_key

Installation

1. Clone the repository:

git clone https://github.com/yourusername/mcp-telegram-ai-assistant.git
cd mcp-telegram-ai-assistant

2. Install dependencies:

npm install

3. Build and start the server:

npm run build
npm start

💡 Usage

MCP Tool Usage

The server provides two powerful tools for AI-powered communication:

1. generate-thinking:

   • Purpose: Generates AI responses using Gemini and manages delivery
   • Features:
     • Intelligent content generation
     • Automatic response storage
     • Optional Telegram delivery
   • Example Usage:

     {
       "name": "generate-thinking",
       "arguments": {
         "prompt": "Explain the concept of quantum entanglement",
         "sendToTelegram": true
       }
     }

2. send-telegram:

   • Purpose: Direct message delivery to Telegram
   • Features:
     • Markdown formatting support
     • Multi-language compatibility
     • Error handling
   • Example Usage:

     {
       "name": "send-telegram",
       "arguments": {
         "message": "Your research summary is ready!",
         "parseMode": "Markdown"
       }
     }

📁 Project Structure

mcp-telegram-ai-assistant/
├── src/
│   └── index.ts         # Main server code
├── dist/               # Compiled JavaScript
├── output/            # Generated responses
├── .env               # Environment variables
└── package.json       # Project dependencies

🔧 Configuration

Environment Variables

• GEMINI_API_KEY: Your Google Gemini API key
• TELEGRAM_BOT_TOKEN: Your Telegram bot token
• TELEGRAM_CHAT_ID: Your Telegram chat ID

Customization

You can customize the server by modifying:

• Response formatting in src/index.ts
• Output directory in the configuration
• Message templates for different use cases

📚 Best Practices

1. For Students:

   • Be specific in your prompts
   • Use follow-up questions for clarity
   • Save important responses for later reference

2. For Educators:

   • Structure prompts for clear explanations
   • Use the bot to generate examples
   • Save responses for course material

3. For Researchers:

   • Use detailed prompts for specific topics
   • Combine multiple responses for comprehensive analysis
   • Keep track of generated content with timestamps

🔒 Security

• Environment variables for sensitive data
• Secure file storage for responses
• Rate limiting on requests
• Error handling and logging

🐳 Docker Deployment

Prerequisites

• Docker installed on your system
• All required API keys and tokens (as mentioned in setup above)

Docker Setup Steps

1. Environment Setup

Ensure your .env file is configured as mentioned in the setup section above.

2. Build Docker Image

# Build the image
docker build -t mcp-telegram-ai-assistant .

3. Run Container

# Create output directory for persistent storage
mkdir -p output

# Run the container
docker run -d \
  --name mcp-telegram-ai \
  -p 3000:3000 \
  -v $(pwd)/output:/app/output \
  --env-file .env \
  mcp-telegram-ai-assistant

4. Container Management

# Check container logs
docker logs mcp-telegram-ai

# Stop container
docker stop mcp-telegram-ai

# Start container
docker start mcp-telegram-ai

# Remove container
docker rm mcp-telegram-ai

5. Docker Configuration Details

• Base Image: node:18-slim
• Exposed Port: 3000
• Volume Mount: ./output:/app/output
• Environment Variables: Loaded from .env file
• Auto-restart: Enabled
• Health Check: Every 30 seconds

Docker Troubleshooting

1. Container fails to start:

   • Check logs: docker logs mcp-telegram-ai
   • Verify environment variables in .env
   • Ensure ports are not in use

2. Output files not saving:

   • Check output directory permissions
   • Verify volume mount path
   • Ensure output directory exists

3. Performance issues:

   • Monitor container resources: docker stats mcp-telegram-ai
   • Check system resources
   • Consider adjusting container resource limits

👨‍💻 Developer

Name: Falah.G.Salieh
Country: Iraq
Year: 2025
Project: MCP Telegram AI Assistant

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Developed with ❤️ by Falah.G.Salieh | Iraq © 2025