Telegram MCP Server

An MCP (Model Context Protocol) server that lets Claude send and manage messages in Telegram through a bot. Built for remote deployment (Streamable HTTP) so it keeps working even when your own computer is off — a requirement for using it inside Claude's scheduled routines/automations.

What it can do

Related MCP server: mcp-telegram-claudecode

Step 1 — Create a Telegram bot (2 minutes)

1. Open Telegram, search for @BotFather, and start a chat.

2. Send /newbot, give it a name and a username (must end in bot, e.g. my_claude_alerts_bot).

3. BotFather replies with a token that looks like 123456789:AAExampleTokenValueHere. Copy it — this is your TELEGRAM_BOT_TOKEN. Keep it secret; anyone with it can control your bot.

Step 2 — Deploy the server so it has a public URL

Since the server needs to run even when your computer is off, deploy it to a free hosting platform. Render.com is the simplest option (no credit card needed for the free tier):

1. Push this folder to a new GitHub repository (create one at github.com if needed):

   cd telegram-mcp-server
   git init
   git add .
   git commit -m "Telegram MCP server"
   git branch -M main
   git remote add origin https://github.com/<your-username>/telegram-mcp-server.git
   git push -u origin main

2. Go to render.com → sign up/log in → New + → Web Service.

3. Connect your GitHub account and select the telegram-mcp-server repo.

4. Configure it:

   • Build Command: npm install && npm run build

   • Start Command: npm start

   • Instance Type: Free

5. Under Environment Variables, add:

   • TELEGRAM_BOT_TOKEN = (the token from BotFather)

   • TRANSPORT = http

6. Click Create Web Service. After the first deploy finishes, Render gives you a URL like https://telegram-mcp-server.onrender.com. Your MCP endpoint is that URL + /mcp, e.g. https://telegram-mcp-server.onrender.com/mcp.

Note: on Render's free tier the service sleeps after 15 minutes of inactivity and takes ~30-60s to wake up on the next request. That's fine for occasional routine use; upgrade to a paid instance ($7/mo) if you need it always warm.

(Railway, Fly.io, or any other Node-friendly host work the same way — build command npm install && npm run build, start command npm start, and the same two env vars.)

Step 3 — Connect it to Claude

In claude.ai: Settings → Connectors → Add custom connector, paste your /mcp URL from Step 2, and save. The tools listed above will then be available to Claude, including inside scheduled routines/automations.

Step 4 — Find your chat_id

The bot can only message chats it already knows about:

• To message yourself or a friend: that person must open a chat with the bot (search its @username in Telegram) and send it any message, e.g. /start.

• To message a group: add the bot to the group.

• To message a channel: add the bot as an admin of the channel.

Then, in Claude, ask it to call telegram_get_updates — it will show the chat_id for every chat/group/channel that has messaged the bot. Save that chat_id; you'll reuse it in your routine (e.g. "send a Telegram message to chat_id 123456789 saying ...").

Local development (optional)

npm install
cp .env.example .env   # fill in TELEGRAM_BOT_TOKEN
npm run build

# stdio mode (for Claude Desktop/Claude Code on your own machine)
npm start

# HTTP mode (matches what's deployed)
TRANSPORT=http PORT=3000 npm start

Test with the MCP Inspector:

npx @modelcontextprotocol/inspector

Security notes

• Never commit .env or your bot token to git (.gitignore already excludes .env).

• The bot token grants full control of the bot — treat it like a password.

• This server only calls the official Telegram Bot API (api.telegram.org); it doesn't store any message content itself.