# Telegram Dev MCP server

> Enables AI agents to search official Telegram and TON documentation and validate Python bot code against the latest Bot API schemas.

- Repository: https://github.com/Kay0k1/telegram-dev
- Page: https://hostedmcp.org/servers/kay0k1/telegram-dev
- Transport: stdio
- Stars: 0
- License: MIT
- Latest version: 0.9.0

## Install

### Claude Code

```sh
claude mcp add telegram-dev -- uvx telegram-dev
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "telegram-dev": {
      "command": "uvx",
      "args": [
        "telegram-dev"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "telegram-dev": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "telegram-dev"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"telegram-dev","type":"stdio","command":"uvx","args":["telegram-dev"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "telegram-dev": {
      "command": "uvx",
      "args": [
        "telegram-dev"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add telegram-dev -- uvx telegram-dev
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.telegram-dev]
command = "uvx"
args = ["telegram-dev"]
```

### Gemini CLI

```sh
gemini mcp add -s user telegram-dev uvx -- telegram-dev
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "telegram-dev": {
      "command": "uvx",
      "args": [
        "telegram-dev"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `TELEGRAM_DOC_AUTO_SYNC` | no | no | Set to 0 to disable the background refresh cycle |
| `TELEGRAM_KNOWLEDGE_DB` | no | no | Path to the SQLite documentation cache (default: the user cache directory) |

## Tools (10)

- `search_telegram_docs`: Find the official documentation sections that answer a Telegram or TON development question. Use it before writing or reviewing code that calls the Bot API, Mini Apps JS, Telegram API/MTProto, TDLib, TON Connect, Tolk contracts or the aiogram, python-telegram-bot and grammY libraries. Returns up to `limit` sections with page URL, heading, excerpt, `document_offset` and freshness. Excerpts are partial: open the page with `get_telegram_document` at `document_offset` before relying on details. Stale matching pages are re-fetched first. An empty result is not proof that a feature does not exist; if the cache is empty, the response suggests pages to fetch. (read-only)
- `get_telegram_document`: Read the text of an official Telegram, TON or bot-library documentation page, one window at a time. Use it to read requirements, parameters and limits in full after `search_telegram_docs` found the page, or to load an entry page from `list_telegram_sources` into an empty cache. Do not use it to find which page answers a question: search first. Pages missing from the cache or older than the freshness limit (6 hours by default) are fetched first. Returns title, URL, Markdown `body` for the requested window, `next_offset` (null at the end), `total_characters`, content hash and freshness. If the live source fails, the cached text is returned with `freshness.stale` and `refresh_error` set. The observation date is when this installation read the page, not when Telegram changed it. (read-only)
- `get_telegram_corpus_status`: Report how complete and how current the local documentation cache is, as totals. Use it at the start of a task or when search results look incomplete. Returns `pages`, per-area counts (`families`), crawl queue state (`frontier`), `stale_pages`, last and oldest successful checks, `refresh_policy` and up to 15 recent source `errors`. For the configured entry points use `list_telegram_sources`; for the individual cached pages use `list_telegram_cached_pages`; to answer a question use `search_telegram_docs`. Refreshing is automatic (on read, on search and in a background cycle), so there is no refresh command. Returns page counts per area, crawl queue state, stale page count, last and oldest successful checks, refresh policy and the latest source errors. Indexed pages are not all of Telegram's knowledge: absence from the cache is not evidence that a feature does not exist. (read-only)
- `list_telegram_document_revisions`: List the revisions of one documentation page that this installation has observed, newest first. Use it to see whether a page changed since an earlier read. To read the current text use `get_telegram_document`. Returns `revisions`: a list of {sha, captured_at, characters}, newest first. A page that this installation has never fetched returns an empty list; a URL outside the official sources is rejected with an error. It does not reconstruct history before the page was first fetched here; for Telegram release history use `list_bot_api_changes` or the changelogs (area `releases` or `ton-releases`). (read-only)
- `list_telegram_sources`: List the official entry points this server crawls, each with its documentation area. Use it to find where to start reading for an unfamiliar area (for example the Bot API index, docs.ton.org/llms.txt or a library's docs) and pass the URL to `get_telegram_document`. If you already know the feature or API name, use `search_telegram_docs` instead. Returns `sources`: a list of {url, area} in the configured order (Telegram core docs, then TON, then bot libraries), and a short `scope` note. This is the source configuration, not the cache: `list_telegram_cached_pages` shows what is already stored. (read-only)
- `list_telegram_cached_pages`: List the documentation pages already stored in the local cache, sorted by URL. Use it to see which pages of an area are available offline or to pick a page to open with `get_telegram_document`. Filter with `area`, page through results with `offset` and `limit`. Returns `pages` (url, title, area, checked_at, freshness), `total` matching pages and `next_offset` to pass back for the next page (null at the end). It lists stored pages only; to find content by topic use `search_telegram_docs`, and for totals and errors use `get_telegram_corpus_status`. (read-only)
- `get_bot_api_definition`: Return the current definition of one Bot API method or type as structured data. Use it instead of reading the whole Bot API page when you need a method's parameters or a type's fields: each entry has its type, whether it is required, the description and any allowed values or length limits stated by Telegram, plus the changelog entries that mention it. For behaviour explained in prose elsewhere (formatting, payments, limits pages) use `search_telegram_docs` and `get_telegram_document`. Returns `kind` (method or type), `name`, `url`, `description`, then `params` (methods; with `returns`) or `fields` (types; or `one_of` for union types), plus `changes`, `bot_api_version`, `source`, `checked_at` and `freshness`. An unknown name returns `kind: null` with close-match `suggestions`. Built from the cached official page, refreshed when stale. (read-only)
- `check_bot_api_call`: Check a Bot API request against the current official schema before running or shipping code. Reports errors (unknown method or parameter with suggestions, missing required parameters, wrong types, values outside the documented list, a wrong `type` in union objects such as InputMedia) and warnings (lengths outside documented limits, parameters retired in an older Bot API version with the changelog entry that replaced them, numbers or booleans sent as strings). It does not call Telegram and cannot check permissions, chat state or file contents. Returns `valid` (true when there are no errors), `errors` and `warnings` as lists of {path, message} where path points into params (for example `reply_markup.inline_keyboard[0][0].style`), plus `url`, `bot_api_version` and freshness. An unknown method returns `valid: false` with suggestions. Use `get_bot_api_definition` to read the definitions it checks against. (read-only)
- `list_bot_api_changes`: List official Bot API changelog entries as structured releases: version, date, link and the individual changes. Use it when upgrading a bot or a library ("what changed since 9.0?"), when a field seems new or missing, or to find when a method or field was added, replaced or removed. Returns `current_version` and `releases`, newest first: each has `version`, `date`, `url` and `changes` ({text, topic, refs: linked methods and types, terms: field and parameter names}). A name that no change mentions returns an empty list. For the full current definition use `get_bot_api_definition`; for TON or library changelogs use `search_telegram_docs` with area `ton-releases` or the library area. (read-only)
- `check_telegram_project`: Check every Bot API call in a Python bot project (aiogram, python-telegram-bot, pyTelegramBotAPI, raw HTTP requests) against the current official schema in one run. Use it after changing an existing bot, before an upgrade, or when asked to review a bot: it reads the whole project locally and returns only findings, so the documentation does not have to enter the context. Errors: values outside the documented list (for example `style="red"`), unknown methods or parameters in raw API requests. Warnings: parameters Telegram retired, with the Bot API version and changelog entry that replaced them; keyword arguments that are neither Bot API parameters nor known library options; bot methods with no Bot API counterpart. It does not run code, follow variables or check required parameters. Returns `findings` ({file, line, severity, call, message}), `errors`, `warnings`, `files_scanned`, declared `libraries` with versions and `bot_api_version`. To check one request instead use `check_bot_api_call`. The same check runs in a shell or CI as `telegram-dev check PATH`. (read-only)

## FAQ

### Do I need a Telegram account or bot token to use this?

No, everything reads public documentation and no Telegram account, bot token, or API key is required.

### Can this tool check my existing Python bot project for errors?

Yes, it can scan Python bots using aiogram, python-telegram-bot, pyTelegramBotAPI, or raw HTTP calls to identify retired parameters or invalid values.

### How does the tool handle the frequent Telegram Bot API updates?

It uses a documentation server and skill that searches over official Telegram and TON docs which are refreshed automatically.
