# 🚀 Telegram Web MCP Server

[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat-square&logo=typescript&logoColor=white)](#)
[![Playwright](https://img.shields.io/badge/Playwright-2EAD33?style=flat-square&logo=playwright&logoColor=white)](#)
[![MCP](https://img.shields.io/badge/MCP-Ready-blueviolet?style=flat-square)](#)

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**
   ```bash
   git clone https://github.com/yourusername/telegram-mcp.git
   cd telegram-mcp
   npm install
   ```

2. **Download Playwright Browsers**
   ```bash
   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**
   ```bash
   npm run build
   ```

4. **Initial Login (Headful Mode)**
   To use Telegram Web, you must log in once. Run the login script:
   ```bash
   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
```json
{
  "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.*