📡 Telegram Topics MCP Server

Official Model Context Protocol (MCP) server that empowers Claude Desktop, Claude Code, and autonomous AI agents to seamlessly route alerts, create topics, and manage Telegram supergroup forum threads.

💡 Why This Exists

Modern AI workflows run continuous tasks: coding iterations, automated research, data scraping, and daily summaries. Routing all agent output into a single Telegram channel creates unreadable noise.

Telegram Forum Topics solve this by creating dedicated sub-threads (e.g., #engineering, #marketing, #financial-audits). This MCP server gives Claude native tools to:

1. Send targeted updates directly into the right topic thread (send_topic_message).

2. Create new discussion threads on the fly for new projects or incident tickets (create_forum_topic).

3. Archive/Close topics when tasks or sprints are completed (close_forum_topic).

4. Resolve division tags into specific thread_ids automatically (list_registered_topics).

Related MCP server: SimpleTgChatMcp

🛠️ Available MCP Tools

🚀 Setup & Integration

1. Prerequisites

• A Telegram Supergroup with Topics enabled (Group Settings → Topics: On).

• A Telegram Bot Token from @BotFather added as an Administrator in the group with Manage Topics permission.

• Your Supergroup Chat ID (e.g., -100xxxxxxxxxx).

2. Integration with Claude Code CLI

Add this MCP server to your Claude Code workspace in one command:

claude mcp add telegram-topics -- python3 /path/to/server.py

Set environment variables in your terminal:

export TELEGRAM_BOT_TOKEN="your_bot_token"
export TELEGRAM_CHAT_ID="-100xxxxxxxxxx"
# Optional topic routing shortcut:
export TELEGRAM_TOPIC_MAP='{"ENGINEERING": 1760, "MARKETING": 137, "GENERAL": 1}'

3. Integration with Claude Desktop

Open your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server under mcpServers:

{
  "mcpServers": {
    "telegram-topics": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp-telegram-topics/server.py"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
        "TELEGRAM_CHAT_ID": "-100xxxxxxxxxx",
        "TELEGRAM_TOPIC_MAP": "{\"DEV\": 1760, \"MARKETING\": 137}"
      }
    }
  }
}

Restart Claude Desktop. You will see the hammer icon 🔨 with Telegram tools active!

💬 Example Prompt in Claude

"Claude, analyze the bug in auth.py, fix it, and send a completion summary to our Engineering topic thread on Telegram."

Claude will automatically:

1. Inspect the code and patch the issue.

2. Call send_topic_message(thread_id=1760, message="✅ Fixed JWT expiration bug in auth.py").

📄 License

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