DEV Community

Cover image for How to Give Your AI Agent Access to Telegram Data (MCP + REST API)
James Tiron
James Tiron

Posted on

How to Give Your AI Agent Access to Telegram Data (MCP + REST API)

#ai #mcp #telegram #python

So I needed my AI agent to pull messages from Telegram channels. Sounds simple. Turns out it's kind of a pain.

The Bot API won't let you read channels unless your bot is added as a member. Telethon and Pyrogram work, but you have to self-host them, deal with phone number auth, and babysit session management yourself. I didn't want any of that. I just wanted a REST endpoint I could hit.

I ended up using this Telegram API on RapidAPI. It sits on top of MTProto (Telegram's native protocol), exposes 12 endpoints as both REST and MCP tools, and has a free tier with 2,500 requests/month. I'm still on that free plan and haven't needed more. No bot tokens, no phone numbers, no infra to maintain.

Here's how I set it up.

What you get

Once connected, your agent can:

  • Read messages from any public Telegram channel
  • Search across all public channels by keyword
  • Get channel details: member count, description, linked group
  • Look up user profiles (bio, premium status, etc.)

12 tools total, all available through one MCP endpoint.

The architecture

Nothing fancy:

Your AI Agent  ──MCP──▶  TG Gateway API  ──MTProto──▶  Telegram
                         (12 tools)                     (public data)
Enter fullscreen mode Exit fullscreen mode

The API handles MTProto sessions, account rotation, and rate limiting under the hood. You just make HTTP calls.

Step 1: Grab an API key

Head to the API page on RapidAPI, hit "Subscribe to Test", pick the Basic plan. It's $0, no credit card. You get 2,500 req/month, which has been plenty for me.

Copy your X-RapidAPI-Key from the dashboard. That's your only credential.

Step 2: Connect via MCP

If you're using Claude, LangChain, CrewAI, or n8n, you can connect through MCP directly. The endpoint uses Streamable HTTP (protocol 2025-06-18):

POST https://telegram-public-api.p.rapidapi.com/v1/mcp
Enter fullscreen mode Exit fullscreen mode

Initialize a session first:

curl -X POST "https://telegram-public-api.p.rapidapi.com/v1/mcp" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "1.0" }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Grab the Mcp-Session-Id from the response headers. You'll pass it in every follow-up call.

Then list the tools:

curl -X POST "https://telegram-public-api.p.rapidapi.com/v1/mcp" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}'
Enter fullscreen mode Exit fullscreen mode

You'll get back these 12:

Tool Does what
tg_resolve_username @username → peer ID
tg_search_contacts Find channels and users
tg_search_global Search messages across all public channels
tg_get_full_user User profile: bio, premium, birthday
tg_get_full_channel Channel info: description, member count
tg_get_history Message history, paginated
tg_get_channel_messages Specific messages by ID
tg_get_replies Comments on a channel post
tg_get_discussion_message Jump to discussion thread
tg_get_channel_participants Channel members list
tg_get_channel_recommendations Similar channels
tg_check_chat_invite Preview invite link without joining

And call one:

curl -X POST "https://telegram-public-api.p.rapidapi.com/v1/mcp" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "tg_resolve_username",
      "arguments": { "username": "telegram" }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

That's it. Your agent now has Telegram access.

Step 3: Or just use Python

If MCP is overkill for your case, there's a Python client:

pip install rapidapi-telegram
Enter fullscreen mode Exit fullscreen mode 
from rapidapi_telegram import TelegramClient

client = TelegramClient(api_key="YOUR_RAPIDAPI_KEY")

# Resolve a username to a peer ID
resolved = client.resolve_username("telegram")
print(resolved)
# → {"Peer": {"UserID": 1005640892}, "Users": [...]}

# Get channel info in one call
channel = client.get_channel_by_username("telegram")
print(f"Members: {channel['FullChat']['ParticipantsCount']}")

# Last 10 messages
history = client.get_history_by_username("telegram", limit=10)
for msg in history["messages"]:
    print(f"  {msg['message'][:80]}...")

# Global search. This one's my favorite.
results = client.search_messages("bitcoin", limit=5)
for msg in results["messages"]:
    print(f"  [{msg['views']} views] {msg['message'][:60]}...")
Enter fullscreen mode Exit fullscreen mode

The get_*_by_username helpers are nice. They resolve the username and fetch data in one call, so you don't have to chain requests manually.

Two things I actually built with this

Channel monitor

Dead simple. Polls a channel every minute, prints anything new:

from rapidapi_telegram import TelegramClient
import time

client = TelegramClient(api_key="YOUR_RAPIDAPI_KEY")

channel = "telegram"  # swap for whatever channel you want
last_id = 0

print(f"Monitoring @{channel}...")

while True:
    history = client.get_history_by_username(channel, limit=5, min_id=last_id)
    messages = history.get("messages", [])

    for msg in reversed(messages):
        text = msg.get("message", "")
        if text:
            views = msg.get("views", 0)
            print(f"[{views:,} views] {text[:120]}")
        last_id = max(last_id, msg.get("id", 0))

    time.sleep(60)
Enter fullscreen mode Exit fullscreen mode

At one poll per minute, this burns ~1,440 requests/day. On the free tier I can run it for about 40 hours straight before hitting the cap. Enough for when I need to keep an eye on something.

Keyword alert across all channels

This is where the global search really shines:

from rapidapi_telegram import TelegramClient

client = TelegramClient(api_key="YOUR_RAPIDAPI_KEY")

results = client.search_messages("breaking OR launch", limit=20)

for msg in results.get("messages", []):
    text = msg.get("message", "")
    channel_id = msg.get("peer_id", {}).get("channel_id")
    views = msg.get("views", 0)
    print(f"Channel {channel_id} [{views:,} views]: {text[:100]}...")
Enter fullscreen mode Exit fullscreen mode

You can search across all public Telegram channels at once. Try doing that with the Bot API (spoiler: you can't).

Bot API vs. this: quick comparison

I keep getting asked this, so here's the short version:

Bot API MTProto API
Read any public channel Nope, bot has to be added Yep, any public channel
Global message search Not a thing Works great
Channel members Bot needs admin Public channels, no problem
User profiles Very limited Full: bio, birthday, premium
Setup Create bot, manage token, add to channels One API key
MCP No Yes, native

If you just need to send messages from a bot, the Bot API is fine. But if you need to read public data (channels, messages, profiles), MTProto is the way.

On cost

Everything above runs on the free tier. I haven't paid anything. There are paid plans if you need high volume, but honestly, for personal projects and prototyping, the free 2,500/month is solid.

Links

If you end up building something with this, drop a comment. I'm curious what people use it for.

Top comments (0)