telegram-bot-mcp

An MCP server that lets Claude manage a Telegram channel through the Telegram Bot API — track subscriber growth day over day, and publish, edit, pin, or delete posts.

🇮🇷 راهنمای فارسی · Deployment guide · راهنمای دپلوی

What this is

Telegram's Bot API is a plain HTTPS API. This repository wraps it in the Model Context Protocol so an AI assistant can call it as tools — "how did the channel do this week?" instead of curl https://api.telegram.org/bot.../getChatMemberCount.

It ships in two forms, from the same tool definitions:

Pick the remote server if you want daily reports that run without you. Pick the plugin if you only use Claude Code and prefer nothing leaving your machine.

Tools

Both builds expose the same eight tools.

Quick start (remote server)

1. Create a bot with @BotFather → /newbot → copy the token.

2. Add the bot as an administrator of your channel.

3. Create an HTTP val on val.town and paste in remote/telegram-mcp.ts.

4. Set three environment variables in the val's sidebar: TELEGRAM_BOT_TOKEN, TELEGRAM_CHANNEL, MCP_PASSWORD.

5. In Claude: Settings → Connectors → Add custom connector → https://<your-val>.web.val.run/mcp → enter your password.

Full walkthrough, including the local plugin path and troubleshooting: docs/deployment.md.

Security

No credentials are committed to this repository. config.json and .env are gitignored; only .example files are tracked. Before pushing any fork, confirm with git status that neither appears.

The remote server implements a full OAuth 2.1 authorization flow rather than sitting open on the internet:

• Requests without a valid bearer token get 401 with a WWW-Authenticate header pointing at the resource metadata, per RFC 9728.

• Clients register dynamically (RFC 7591); no client secrets to distribute.

• Authorization codes are protected with PKCE (S256), and redirect URIs are validated against the registered set.

• Access and refresh tokens are HMAC-SHA256 signed and stateless — 24-hour access, 30-day refresh.

• The consent screen is gated by MCP_PASSWORD, which you choose.

Your bot token stays in the host's environment variables and is never returned by any tool.

Treat MCP_PASSWORD like a password to your channel. Anyone who has it can connect and publish posts.

Limitations

The Bot API reports subscriber counts only. Post views, forwards, reach, and Telegram's official channel-statistics graphs are not exposed to bots — those require an MTProto client signed in with a user account that administers the channel.

A bot can generally only edit messages it sent itself. Telegram defines a can_edit_messages administrator right ("can edit messages of other users; for channels only"), but bot behaviour against posts published by human admins is not clearly documented — test it against your own channel before relying on it. Deletion is different: can_delete_messages explicitly covers other users' messages.

Growth comparison requires the history store to survive between runs. On Val Town that is blob storage and it persists. In the local plugin it is a CSV file — keep it somewhere durable, not a temp directory.

Repository layout

remote/telegram-mcp.ts              Remote MCP server (Val Town HTTP val, Deno)
plugin/                             Claude Code plugin
  .claude-plugin/plugin.json          Plugin manifest
  .mcp.json                           stdio MCP server registration
  server/telegram_mcp_server.py        MCP server (Python 3, stdlib only)
  skills/telegram-channel-report/      Skill that turns tools into a readable report
  config.example.json                  Template — copy to config.json
tests/                              Test suite for the remote server
docs/                               Deployment guides (English / فارسی)

Tests

npm test

Requires Node 22.6+. Twenty-two checks cover the OAuth flow (401 challenge, discovery documents, dynamic registration, PKCE rejection, token and refresh grants, forged-token rejection) and the MCP protocol (initialize, notifications, tool listing, growth-delta arithmetic, tool error paths). The Telegram API is mocked; no network access and no real bot token are needed.

The suite runs against the deployed source itself — tests/build.mjs rewrites exactly one line, the Val Town blob import, and changes nothing else.

License

MIT