🚀 Telegram Web MCP Server

A powerful, token-efficient Model Context Protocol (MCP) server for AI Agents to interact with Telegram Web.

Instead of forcing your AI (like Claude, Antigravity, or Cursor) to use heavy browser automation subagents that waste tokens analyzing DOM trees and screenshots, this server provides a clean, text-based API to interact with Telegram chats directly via a persistent Playwright session.

✨ Features

• Token Efficient: Returns clean text instead of complex HTML DOMs.

• Persistent Session: Log in once, and the session is saved forever.

• Smart Tools:

  • search_chats - Find and open a chat by username.

  • get_recent_chats - Retrieve recent chat names/titles and metadata from the sidebar.

  • get_chat_history - Get the most recent text messages.

  • get_profile_info - Retrieve user profiles and bios.

  • send_message - Send messages directly to the active chat.

  • send_file - Upload documents/files to a specified chat.

  • send_photo - Upload images/photos to a specified chat.

  • reply_to_message - Reply directly to a specific target message.

• AI-Ready Skills: Includes dedicated skill guides to teach your AI exactly how to use these tools without sounding like a robot.

Related MCP server: telegram-mcp

📦 Installation & Setup (For Humans)

1. Clone & Install Dependencies

   git clone https://github.com/yourusername/telegram-mcp.git
   cd telegram-mcp
   npm install

2. Download Playwright Browsers

   npm run setup

   (Note: This command installs the necessary Chromium binaries. If it fails due to network issues, try connecting via VPN).

3. Build the Project

   npm run build

4. Initial Login (Headful Mode) To use Telegram Web, you must log in once. Run the login script:

   npm run login

   A browser window will appear. Scan the QR code with your Telegram app on your phone. Once you see your chats, close the browser window. Your session is now saved in the telegram_profile/ folder!

🤖 Integration (For AI Agents)

Add this server to your AI's MCP configuration file (e.g., in Antigravity or Claude Desktop).

MCP Configuration Example

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/absolute/path/to/telegram-mcp/build/index.js"]
    }
  }
}

🧠 Teach your AI how to use it!

We have provided a ready-to-use Skill for your AI. Simply copy the skills/telegram-mcp/ folder into your AI's custom skills directory (for example, .gemini/config/skills/). The AI will read this file and instantly learn the best practices for chatting like a real human!

🛠️ Available MCP Tools

Built with ❤️ for the AI Automation community.