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

---

📦 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

Tool Name	Description	Parameters
search_chats	Find and open a chat by username	query: string
get_recent_chats	Retrieve a list of recent chat names/titles and metadata from the left sidebar	limit?: number (default: 10)
get_chat_history	Get recent text messages from the currently open chat	limit?: number (default: 20)
get_profile_info	Get profile info of the currently open chat	none
send_message	Send a message to the currently open chat	text: string
send_file	Upload a document or file to a specified chat (or currently open chat)	filePath: string, caption?: string, chat?: string
send_photo	Upload an image/photo to a specified chat (or currently open chat)	filePath: string, caption?: string, chat?: string
reply_to_message	Reply directly to a target message in a chat	messageTextOrId: string, replyText: string, chat?: string

---

Built with ❤️ for the AI Automation community.