io.github.Shreyas-Profile/telegram-mcp — Telegram MCP Bridge

This MCP server provides a bidirectional Telegram ⇆ agent bridge for MCP-compatible agents. Telegram messages are received, stored, and then delivered to an agent when it polls. Responses produced by the agent are sent back through the same platform to Telegram. The stack is described as having no inference in the middle.

🛠️ Key Features

Bidirectional Telegram ⇆ agent bridge
Message intake from Telegram with storage
Delivery to an agent on poll
Agent-to-Telegram responses forwarded back
“No inference in the middle” / no LLM calls in the platform

🚀 Use Cases

Use Telegram as the messaging interface for an MCP-compatible agent
Connect agents such as Claude Desktop, Cursor, or a custom script to Telegram

⚡ Developer Benefits

Bring your own agent; any MCP client works
No vendor lock-in is stated (since no LLM is called in the middle)
Agent is the “brain”; platform acts as a message pipe

⚠️ Limitations

The provided description focuses on message bridging; no additional capabilities beyond Telegram ↔ agent forwarding are specified

telegram-mcp

Built by Shreyas · Shipped by Globalion

Bidirectional Telegram ⇆ agent bridge. No LLM in our stack.

Your agent (Claude Desktop, Cursor, a custom script) is the brain. Our platform is the pipe: we take messages you send on Telegram, store them, and hand them to your agent when it polls. When your agent has something to say back, it pushes through us to your Telegram.

Bring your own agent. Any MCP client works.
No inference in the middle. We don't call an LLM. No vendor lock-in.
Bidirectional. get_new_messages pulls inbound, send_telegram_message pushes outbound.
Platform slash-commands. /help, /clear, /recent, /window, /usage all work even if your agent is offline.

Hosted at telegram.regiq.in or self-host with the Docker Compose below.

Use it (hosted)

Visit https://telegram.regiq.in, sign in with Google.
DM @BotFather → /newbot. Paste the token in your dashboard.
On the dashboard: Generate MCP API key, copy it.

Add to Claude Desktop's claude_desktop_config.json (or Cursor / any MCP client):

json

{
  "mcpServers": {
    "telegram": {
      "url": "https://telegram.regiq.in/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY_HERE"
      }
    }
  }
}

Send /start to your bot on Telegram.

Now your agent can call get_new_messages to see what you sent it, and send_telegram_message to reply.

Tools

Tool	Direction	Notes
`get_new_messages()`	user → agent	Returns inbound messages since the last pull. Read-once.
`send_telegram_message(text)`	agent → user	Delivers text to the user's Telegram bot.
`list_recent_messages(max=20)`	read	Last N stored messages, both directions. No cursor advance.
`clear_history()`	action	Wipes stored history for the user.

Slash commands (platform-handled)

Handled by the platform directly — your agent isn't involved. So /help works even when nothing is polling.

Command	Effect
`/start`	Registers this Telegram chat with your account.
`/help`	Lists commands.
`/recent [N]`	Shows the last N stored messages.
`/clear`	Wipes history.
`/window N`	Sets the history window (default 20).
`/usage`	Stored message count.

Self-host

You'll need:

Docker + Compose
A Google OAuth client — Cloud Console. Scopes: openid, email, profile. Redirect: <PUBLIC_BASE_URL>/api/auth/callback/google
A public HTTPS domain for Telegram webhooks (Cloudflare Tunnel or ngrok http 3012 locally)

No LLM key required. Your agent brings its own model.

bash

git clone https://github.com/globalion/telegram-mcp
cd telegram-mcp
cp .env.example .env
# fill NEXTAUTH_SECRET, GOOGLE_*, PUBLIC_BASE_URL
docker compose up -d
# open http://localhost:3012

Architecture

code

  Telegram app                                Your MCP agent
     ▲   │                                      ▲   │
     │   │ text                          poll   │   │ push
     │   ▼                                      │   ▼
   ┌──────────────────────────────────────────────────┐
   │  Our platform (Hetzner)                          │
   │  - /api/telegram/webhook/<per-user-secret>       │
   │    · slash-commands answered here                │
   │    · plain text stored, no reply                 │
   │  - /api/mcp   Bearer-auth JSON-RPC               │
   │    · get_new_messages, send_telegram_message     │
   │    · list_recent_messages, clear_history         │
   │  - Postgres: User, ApiKey, TelegramLink, Message │
   └──────────────────────────────────────────────────┘

Per-user webhook URL segment is a random secret so a leaked bot token can't be pointed at someone else's account. Google sign-in is identity + ban anchor only — per-message identity comes from the MCP API key + chatId.

License

MIT. See LICENSE.

io.github.Shreyas-Profile/telegram-mcp