Qwen Code Telegram Server

Version: v2.2.0

MCP Server for Telegram Bot integration with Qwen Code. Chat with Qwen Code directly from Telegram with persistent sessions, group chat support, and advanced features.

---

🌟 Features

Core Features

• 🤖 Telegram Bot Integration - Full Telegram Bot API via long polling
• 🔌 MCP Protocol Support - Native integration with Qwen Code
• 💬 Persistent Sessions - File-based conversation history (survives restarts)
• 🔐 Pairing System - 6-digit code security for access control
• ⌨️ Typing Indicators - Better UX while processing
• 📊 Admin Commands - Session management and monitoring
• 🧹 Auto-Cleanup - Automatic maintenance for old sessions
• 🔧 Dynamic Configuration - Workspace-specific settings

v2.2.0 New Features

• 👥 Group Chat Support - Bot works in groups without crashes!
• 📢 Mention-Based Trigger - Bot responds only when mentioned (@bot_name)
• 💭 Quoted Message Context - Bot reads reply/quote messages
• 🔇 Silent Ignore - No spam in groups (ignores non-mentions)
• 🎯 Smart Reply - Auto-reply to original message for better UX
• 📈 Metrics Tracking - Request count and token usage monitoring

---

🚀 Quick Start

For Qwen Code Users (Vibe Coding)

🎯 EASIEST METHOD: Let your LLM agent handle everything!

After cloning this repository, simply tell your Qwen Code:

@qwen Read and implement VIBE-INSTALL.md for installation, 
then VIBE-CONFIG.md for configuration. Ask me for confirmation 
before any sensitive data.

Your LLM agent will:

1. ✅ Install all dependencies automatically
2. ✅ Build the TypeScript project
3. ✅ Guide you through Telegram bot creation
4. ✅ Configure Qwen Code MCP settings
5. ✅ Test everything works

📚 Vibe Coding Guides:

• 📦 VIBE-INSTALL.md - Automated installation
• ⚙️ VIBE-CONFIG.md - Automated configuration
• 🛠️ VIBE-REPAIR.md - Automated troubleshooting

---

Special Note from the Human This is the only section touched by human. Everything in this MCP is vibe-coded but safely structured. If something messed up, simply run your agent. It will do the complex thing for you. Wanted new features? Ask your agent.

My agent clears the path. Yours should follow. -JavaIsKey

---

Manual Installation

Prerequisites

• Node.js >= 18.x
• npm >= 9.x
• Git

Steps

1. Clone repository

git clone https://github.com/YOUR_USERNAME/qwen-code-telegram-mcp.git
cd qwen-code-telegram-mcp

2. Install dependencies

npm install

3. Build TypeScript

npm run build

4. Setup environment

cp .env.example .env
# Edit .env with your configuration

5. Configure Qwen Code

Add to ~/.qwen/settings.json:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["[YOUR_PATH]/dist/index.js"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "${TELEGRAM_BOT_TOKEN}",
        "WORKSPACE_PATH": "[YOUR_WORKSPACE_PATH]"
      }
    }
  }
}

6. Start Qwen Code

npx qwen

7. Chat with your bot on Telegram!

---

📱 Telegram Bot Setup

Create New Bot

1. Open Telegram → Search @BotFather
2. Send /newbot
3. Follow instructions:
   • Choose name: My Assistant
   • Choose username: my_assistant_bot
4. Copy the bot token (format: 123456789:ABCdef...)

⚠️ IMPORTANT: Disable Privacy Mode

For group chat support:

1. @BotFather → /setprivacy
2. Select your bot
3. Choose: "Disable privacy"

Without this, bot won't read group messages!

---

🎮 Usage

Private Chat

Just send message to bot:

User: Hello
Bot: [AI response from Qwen Code]

Group Chat

Must mention bot:

User: @my_bot_name What's the capital of France?
Bot: [AI response]

User: hello everyone
Bot: [Ignored - no mention]

With quoted message:

User 1: [sends message] "This is important"
User 2: [reply] @my_bot_name summarize this
Bot: [Reads quoted message + instruction]

---

📋 Available Commands

User Commands

• /start - Welcome message + pairing instructions
• /help - Help information
• /status - Server status
• /session - Your session info
• /clear - Clear your session
• /whoami - Your Telegram info
• /ask <question> - Ask Qwen Code directly
• /pair <CODE> - Pair bot with code
• /approvalmode [mode] - Set approval mode (plan/auto-accept/yolo)

Admin Commands

• /sessions - List all active sessions

---

🔐 Pairing System

How It Works

1. User messages bot - Bot checks if user is paired
2. Admin generates code - Via MCP tool:

   generate_telegram_pairing_code
   

3. User pairs - User runs:

   /pair ABC123
   

4. Access granted - User now has access

Pairing Code Properties

• 6 characters (uppercase alphanumeric)
• Valid for 15 minutes
• One-time use
• Auto-cleanup when expired

---

📁 Project Structure

qwen-code-telegram-mcp/
├── src/
│   └── index.ts              # Main code (2300+ lines)
├── dist/
│   └── index.js              # Compiled code
├── .env                      # Environment config
├── .env.example              # Example config
├── package.json              # Dependencies
├── tsconfig.json             # TypeScript config
├── README.md                 # This file
├── DOCUMENTATION.md          # Detailed documentation
├── VIBE-INSTALL.md           # LLM agent installation guide
├── VIBE-CONFIG.md            # LLM agent configuration guide
└── VIBE-REPAIR.md            # LLM agent troubleshooting guide

Workspace/
├── temp/
│   ├── telegram-bot.log              # Runtime log
│   └── telegram-sessions/
│       ├── {chatId}.json             # User sessions
│       ├── allowlist.json            # Paired users
│       └── approval-modes.json       # Approval modes
└── .qwen/
    └── commands/
        └── *.md                      # Custom commands

---

⚙️ Configuration

Environment Variables

Copy .env.example to .env and configure:

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_bot_token_here

# Workspace Configuration
WORKSPACE_PATH=/path/to/your/workspace

# MCP Server Configuration
MCP_SERVER_PORT=3000
MCP_TRANSPORT=stdio

Session Settings

Setting	Default	Description
MAX_CONVERSATION_HISTORY	50	Max messages per session
INACTIVE_CHAT_TIMEOUT_MS	86400000	Session expiry (24h)

---

🛠️ Development

# Build TypeScript
npm run build

# Run development mode
npm run dev

# Run production
npm start

---

🐛 Troubleshooting

Bot not responding

Check:

1. Bot token valid? → @BotFather
2. Bot running in Qwen Code?
3. Privacy mode disabled? → /setprivacy

Session not saving

Check:

1. WORKSPACE_PATH correct?
2. Folder has write permission?
3. temp/telegram-sessions/ exists?

Pairing code not working

Check:

1. Code not expired (15 min only)
2. Code entered correctly (uppercase)
3. User in allowlist?

Need Help?

👉 See VIBE-REPAIR.md for comprehensive troubleshooting guide!

---

📊 Metrics Tracking

Bot automatically tracks:

• totalRequests - Total message count
• totalErrors - Error count
• tokens.total - Estimated token usage
• tokens.prompt - Input tokens
• tokens.output - Output tokens

View with: /status command

---

🧪 Testing Checklist

Basic Functionality

• DM: hello → AI response
• Group: @bot_name test → AI response
• Group: test (no mention) → Ignored
• Custom command: /health → Executed

Sessions

• Session file created
• Session persists after restart
• /clear deletes session
• /session shows correct info

Pairing

• Unpaired → Access denied
• Generate code → Works
• /pair ABC123 → Success
• Invalid code → Rejected

Files

• Send document → Processed
• Send photo → Downloaded
• send_telegram_file → Works

Logging

• Log file created
• Messages logged
• Errors logged
• No infinite loops

---

📝 Version History

v2.2.0 (Current)

• ✅ Full group chat support
• ✅ Mention-based triggering
• ✅ Quoted message context
• ✅ Telegram auto-correct handling
• ✅ Metrics tracking

v2.1

• Multi-bot support via workspace-specific MCP config

v2.0

• Persistent sessions
• Pairing system
• Typing indicators
• Admin commands

v1.0

• Initial release with basic MCP integration

---

📚 Documentation

• VIBE-INSTALL.md - LLM agent installation guide
• VIBE-CONFIG.md - LLM agent configuration guide
• VIBE-REPAIR.md - LLM agent troubleshooting guide
• DOCUMENTATION.md - Detailed technical documentation
• CONTRIBUTING.md - Contribution guidelines
• CODE_OF_CONDUCT.md - Code of conduct

---

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

Quick Contributing

1. Fork repository
2. Create branch: git checkout -b feature/your-feature
3. Make changes
4. Test thoroughly
5. Submit PR

---

📄 License

ISC License - see LICENSE file.

---

🆘 Support

For Issues:

1. Check VIBE-REPAIR.md first
2. Review logs: temp/telegram-bot.log
3. Create GitHub issue with:
   • Error message
   • What you were doing
   • Your environment (Node.js, OS)

For Questions:

• Create GitHub Discussion
• Check DOCUMENTATION.md

---

🎯 Why Vibe Coding?

This project is designed for Qwen Code vibe coding:

• ✅ LLM-Friendly Setup - VIBE-* guides for automated installation
• ✅ Zero Configuration - LLM agent handles everything
• ✅ Smart Troubleshooting - VIBE-REPAIR for automated fixes
• ✅ User Confirmation - Sensitive data requires user approval
• ✅ Well Documented - Every step clearly explained

Just clone and let your LLM agent do the work! 🚀

---

Built with ❤️ for Qwen Code
Last updated: 2026-03-26