🚀 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 any chat by username.

  • get_chat_history - Get the most recent text messages.

  • send_message - Send messages directly to the active chat.

  • get_profile_info - Retrieve user profiles and bios.

• AI-Ready Skills: Includes a dedicated SKILL.md file to teach your AI exactly how to use this tool without sounding like a robot.

Related MCP server: playwright-browser

📦 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.