<div align="center">

# ✈️ TgPilot

**Give Claude, Cursor or any MCP-compatible AI agent your Telegram account.**

Read chats, get unread digests, search history, reply, forward, post to channels, manage groups —
by just asking your AI in plain language.

[![PyPI](https://img.shields.io/badge/pip_install-tgpilot-3776AB?style=for-the-badge&logo=python&logoColor=white)](#-install)
[![MCP](https://img.shields.io/badge/MCP-server-8b5cf6?style=for-the-badge)](https://modelcontextprotocol.io)
[![Telegram](https://img.shields.io/badge/Telegram-user_account-26A5E4?style=for-the-badge&logo=telegram&logoColor=white)](#)
[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e?style=for-the-badge)](LICENSE)

</div>

```text
You:    What did I miss in Telegram this morning? Reply to Alex that I'll be there at 7.
Claude: You have 4 unread chats:
        • Alex — asks if you're coming to dinner tonight
        • Design team — new mockups for the landing page (3 files)
        • Mom — "call me when you're free"
        • @durov channel — 1 new post
        ✅ Replied to Alex: "Sure, I'll be there at 7!"
```

## Why TgPilot

- 🧠 **Works with any MCP client** — Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Zed, n8n, your own agent.
- 👤 **Real user account**, not a bot: everything you can do in the Telegram app, your agent can do too.
- 🛡 **Safety first** — read-only mode, allow / deny lists of chats, rate-limit handling, no data leaves your machine.
- 🙋 **Human-like** — shows "typing…" with a natural pause before messaging people.
- ⚡ **One command** to log in, one line of config to connect. No database, no bot token, session is a single string.

## 🧰 Tools

| Read | Act |
|---|---|
| `get_me` — account info | `send_message` — text, reply, scheduled send |
| `list_dialogs` — recent chats & unread | `send_file` — photo, video, document, voice |
| `search_chats` — people, groups, channels | `forward_messages` |
| `get_chat_info` — bio, members, about | `edit_message` / `delete_messages` |
| `read_messages` — history with pagination | `react` — emoji reactions |
| `search_messages` — in one chat or everywhere | `pin_message` / `mark_read` |
| `unread_digest` — what you missed | `send_poll` |
| `read_comments` — comments under a post | `join_chat` / `leave_chat` |
| `get_participants` — group members | `create_group` — group or channel + invite link |
| `download_media` — save media locally | `invite_users`, `update_profile`, `block_user` |

Run `tgpilot tools` to see the list.

## 📦 Install

```bash
pip install git+https://github.com/Shukurov777/tgpilot
# or
uv tool install git+https://github.com/Shukurov777/tgpilot
```

## 🔑 Log in (once)

1. Get `api_id` and `api_hash` at **[my.telegram.org/apps](https://my.telegram.org/apps)**.
2. Run:

```bash
tgpilot login
```

Enter your phone, the code from Telegram and 2FA password (if any). You'll get `TG_SESSION` — a string that
gives full access to the account. **Keep it secret.**

## 🔌 Connect to your AI

<details open>
<summary><b>Claude Desktop</b> — <code>claude_desktop_config.json</code></summary>

```json
{
  "mcpServers": {
    "telegram": {
      "command": "tgpilot",
      "args": ["serve"],
      "env": {
        "TG_API_ID": "123456",
        "TG_API_HASH": "your_api_hash",
        "TG_SESSION": "your_session_string"
      }
    }
  }
}
```
</details>

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add telegram \
  -e TG_API_ID=123456 -e TG_API_HASH=your_api_hash -e TG_SESSION=your_session_string \
  -- tgpilot serve
```
</details>

<details>
<summary><b>Cursor</b> — <code>~/.cursor/mcp.json</code></summary>

```json
{
  "mcpServers": {
    "telegram": {
      "command": "tgpilot",
      "args": ["serve"],
      "env": { "TG_API_ID": "123456", "TG_API_HASH": "your_api_hash", "TG_SESSION": "your_session_string" }
    }
  }
}
```
</details>

<details>
<summary><b>Docker</b></summary>

```bash
docker build -t tgpilot .
docker run -i --rm --env-file .env tgpilot serve
```
</details>

<details>
<summary><b>HTTP (remote agents, n8n, etc.)</b></summary>

```bash
tgpilot serve --transport streamable-http
```
</details>

## ⚙️ Configuration

| Variable | Default | Description |
|---|---|---|
| `TG_API_ID`, `TG_API_HASH` | — | From my.telegram.org |
| `TG_SESSION` | — | Printed by `tgpilot login` |
| `TG_READ_ONLY` | `0` | `1` = only reading tools are exposed (also `serve --read-only`) |
| `TG_HUMAN_LIKE` | `1` | "typing…" and a short pause before messaging people |
| `TG_ALLOW_CHATS` | empty | Comma list of `@usernames` / ids the agent may access. Empty = all |
| `TG_DENY_CHATS` | empty | Chats the agent must never see or touch |
| `TG_DOWNLOAD_DIR` | `~/.tgpilot/downloads` | Where `download_media` saves files |

## 💡 Ideas to try

- *"Give me a digest of all unread chats, grouped by importance."*
- *"Find who sent me the invoice last week and forward it to @accountant."*
- *"Summarize the last 200 messages in the Design team group and post the summary there."*
- *"Create a channel 'Daily AI news' and post today's top 5 headlines."*
- *"Every message from @boss — reply that I'll answer within an hour."* (with a scheduler / agent loop)

## 🔒 Security

- Everything runs locally; TgPilot talks only to Telegram servers.
- The session string is equal to your password — store it in env/secret manager, never commit it.
- Start with `--read-only` and `TG_ALLOW_CHATS` until you trust your agent.
- Content of messages is untrusted input. Tool instructions remind the model to treat chats as data, not commands.
- Automating a user account must follow the [Telegram Terms of Service](https://telegram.org/tos). Don't spam.

## 🗺 Roadmap

- [ ] Voice message transcription (Whisper)
- [ ] Stories: view & download
- [ ] Real-time events (new message → agent)
- [ ] Multiple accounts
- [ ] Prompts: daily digest, inbox zero

## 🤝 Contributing

Issues and PRs are welcome. If TgPilot saves you time — **leave a ⭐**, it really helps the project grow.

## License

[MIT](LICENSE) © Bahrullo Shukurov