✈️ 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.

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.

Related MCP server: Telegram MCP Server

🧰 Tools

Run tgpilot tools to see the list.

📦 Install

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.

2. Run:

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

{
  "mcpServers": {
    "telegram": {
      "command": "tgpilot",
      "args": ["serve"],
      "env": {
        "TG_API_ID": "123456",
        "TG_API_HASH": "your_api_hash",
        "TG_SESSION": "your_session_string"
      }
    }
  }
}

claude mcp add telegram \
  -e TG_API_ID=123456 -e TG_API_HASH=your_api_hash -e TG_SESSION=your_session_string \
  -- tgpilot serve

{
  "mcpServers": {
    "telegram": {
      "command": "tgpilot",
      "args": ["serve"],
      "env": { "TG_API_ID": "123456", "TG_API_HASH": "your_api_hash", "TG_SESSION": "your_session_string" }
    }
  }
}

docker build -t tgpilot .
docker run -i --rm --env-file .env tgpilot serve

tgpilot serve --transport streamable-http

⚙️ Configuration

💡 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. 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 © Bahrullo Shukurov