# 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.

**[🇮🇷 راهنمای فارسی](README.fa.md)** · [Deployment guide](docs/deployment.md) · [راهنمای دپلوی](docs/deployment.fa.md)

---

## What this is

Telegram's Bot API is a plain HTTPS API. This repository wraps it in the [Model Context Protocol](https://modelcontextprotocol.io) 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** (`remote/`) | **Local plugin** (`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.

## Tools

Both builds expose the same eight tools.

| Tool | Description |
|---|---|
| `get_channel_info` | Title, username, description, subscriber count, admin count, invite link |
| `get_member_count` | Subscriber count only — fast |
| `snapshot_members` | Record today's count, return the change since the previous snapshot |
| `get_growth_history` | Recorded snapshots with per-day changes and a net-change summary |
| `send_post` | Publish a text post (HTML/Markdown, silent, no-preview options) |
| `edit_post` | Replace the text of a post |
| `delete_post` | Delete a post by message id |
| `pin_post` | Pin or unpin a post |

## Quick start (remote server)

1. Create a bot with [@BotFather](https://t.me/BotFather) → `/newbot` → copy the token.
2. Add the bot as an administrator of your channel.
3. Create an HTTP val on [val.town](https://val.town) and paste in [`remote/telegram-mcp.ts`](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](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](https://datatracker.ietf.org/doc/html/rfc9728).
- Clients register dynamically ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)); 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

```bash
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](LICENSE)