Telegram MCP server

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. getnewmessages pulls inbound, sendtelegrammessage 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)

1. Visit https://telegram.regiq.in, sign in with Google.
2. DM @BotFather → /newbot. Paste the token in your dashboard.
3. On the dashboard: Generate MCP API key, copy it.
4. Add to Claude Desktop's claudedesktopconfig.json (or Cursor / any MCP client):

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

1. Send /start to your bot on Telegram.

Now your agent can call getnewmessages to see what you sent it, and sendtelegrammessage to reply.

Tools

Slash commands (platform-handled)

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

Self-host

You'll need:

• Docker + Compose
• A Google OAuth client — Cloud Console. Scopes: openid, email, profile. Redirect: /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.

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

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 │
   └──────────────────────────────────────────────────┘

Shortened. The full README is on GitHub.