MCP 服务器

Telegram Web MCP Server

Enables AI agents to interact with Telegram Web through a clean text-based API, including chat search, message history, sending messages, and profile retrieval via a persistent Playwright session.

README

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

Clone & Install Dependencies

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

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).
Build the Project
```
npm run build
```
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`