@mcp-registry/mcp-telegram-ai-assistant/README.md

Professional MCP server for AI-powered Telegram communication - Perfect for students, educators, and researchers

# 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

<div align="center">
  
![Demo](video/mcp-telegram-ai-assistant.gif)

  <h3>🎯 Key Features Demonstrated</h3>
  <table>
    <tr>
      <td>✨ Real-time AI Processing</td>
      <td>🌍 Multi-language Support</td>
    </tr>
    <tr>
      <td>📝 Smart Content Generation</td>
      <td>🔄 Automatic Response Storage</td>
    </tr>
    <tr>
      <td>🎨 Professional Formatting</td>
      <td>📱 Instant Telegram Delivery</td>
    </tr>
  </table>
</div>

## 🌟 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](https://t.me/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](https://t.me/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:
     ```env
     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:
```bash
git clone https://github.com/yourusername/mcp-telegram-ai-assistant.git
cd mcp-telegram-ai-assistant
```

2. Install dependencies:
```bash
npm install
```

3. Build and start the server:
```bash
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**:
     ```json
     {
       "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**:
     ```json
     {
       "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
```bash
# Build the image
docker build -t mcp-telegram-ai-assistant .
```

#### 3. Run Container
```bash
# 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
```bash
# 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