# 🚀 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)](#)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)

A powerful, **token-efficient** Model Context Protocol (MCP) server that lets AI agents interact with Telegram Web — without wasting tokens on DOM trees and screenshots.

## 🤔 The Problem

Existing approaches to Telegram automation for AI agents either:
- Require **Telegram Bot API tokens** (limiting you to bot-only features)
- Use **heavy browser automation** that wastes thousands of tokens parsing HTML DOMs and analyzing screenshots
- Provide **no persistent session**, requiring re-authentication every time

## ✅ The Solution

This MCP server provides a **clean, text-based API** layer over a persistent Playwright browser session. Your AI agent gets structured text responses instead of raw HTML — cutting token usage by 10-50x compared to generic browser automation.

## ✨ Features

| Tool | Description |
|---|---|
| `search_chats` | Find and open a chat by username |
| `get_recent_chats` | Retrieve recent chat names/titles and metadata |
| `get_chat_history` | Get the most recent text messages |
| `get_profile_info` | Retrieve user profiles and bios |
| `send_message` | Send messages to the active chat |
| `send_file` | Upload documents/files to a chat |
| `send_photo` | Upload images/photos to a chat |
| `reply_to_message` | Reply directly to a specific message |

### Key Design Decisions

- **🔋 Token Efficient** — Returns clean text, not complex HTML DOMs
- **💾 Persistent Session** — Log in once, session is saved permanently
- **🤖 AI-Ready** — Includes dedicated skill guides for Claude, Cursor, and Antigravity
- **🔒 Local-First** — Runs on your machine, no data sent to third parties

## 📦 Installation

```bash
git clone https://github.com/Fayzullo637/mytelegrammini1-mcp.git
cd mytelegrammini1-mcp
npm install
npx playwright install chromium
```

## 🚀 Usage

### With Claude Desktop / Antigravity

Add to your MCP config:

```json
{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/path/to/mytelegrammini1-mcp"
    }
  }
}
```

Then ask your AI: *"Search for @username on Telegram and send them a message"*

## 🛠️ Tech Stack

- **TypeScript** — Type-safe server implementation
- **Playwright** — Reliable browser automation with persistent contexts
- **MCP SDK** — Standard Model Context Protocol interface

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.