Enables managing a Telegram channel via the Bot API: retrieve channel info and subscriber counts, snapshot daily growth, and publish, edit, delete, or pin posts.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 · راهنمای دپلوی
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:
Remote server ( | Local plugin ( | |
Runs on | Val Town (or any Deno-compatible host) | Your own machine |
Connects via | Claude custom connector (OAuth) | Claude Code plugin (stdio) |
Works in | Claude web, desktop, mobile, scheduled tasks | Claude Code CLI |
Persistence | Val Town blob storage | CSV file on disk |
Auth | Built-in OAuth 2.1 + password gate | Local config file |
Needs your computer on | No | Yes |
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.
Related MCP server: SimpleTgChatMcp
Both builds expose the same eight tools.
Tool | Description |
| Title, username, description, subscriber count, admin count, invite link |
| Subscriber count only — fast |
| Record today's count, return the change since the previous snapshot |
| Recorded snapshots with per-day changes and a net-change summary |
| Publish a text post (HTML/Markdown, silent, no-preview options) |
| Replace the text of a post |
| Delete a post by message id |
| Pin or unpin a post |
Create a bot with @BotFather → /newbot → copy the token.
Add the bot as an administrator of your channel.
Create an HTTP val on val.town and paste in remote/telegram-mcp.ts.
Set three environment variables in the val's sidebar: TELEGRAM_BOT_TOKEN, TELEGRAM_CHANNEL, MCP_PASSWORD.
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.
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.
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.
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 / فارسی)npm testRequires 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Run a Telegram channel from your AI agent. Posts go out through your own bot, not your account.
Let AI assistants post to your Telegram chats, groups and channels. Not affiliated with Telegram.
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
Run social media from Claude: draft, schedule and approve posts, answer comments, read results.