# telegram-mcp-server

[![CI](https://github.com/a-shipilo/telegram-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/a-shipilo/telegram-mcp-server/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

MCP-сервер, через который Claude **пишет вам в Telegram от имени вашего бота**.
Он нужен прежде всего для уведомлений: итог рутины, конец долгой задачи, найденная проблема.
Сервер запускается через `uvx` прямо из GitHub, устанавливать ничего не нужно.

*English: a minimal open-source MCP server that lets Claude send you Telegram messages through your own bot:
notifications from routines, scheduled and long-running tasks. Messages always go to the single chat
configured on the server. Run it with
`uvx --from git+https://github.com/a-shipilo/telegram-mcp-server telegram-mcp-server`.*

## Возможности

| Инструмент | Что делает |
|---|---|
| `send_message` | отправляет сообщение в чат из `TELEGRAM_CHAT_ID` |

Параметры `send_message`:

| Параметр | По умолчанию | Описание |
|---|---|---|
| `text` | — | текст сообщения, обязательно |
| `format` | `html` | `html` — [разметка тегами Telegram](https://core.telegram.org/bots/api#html-style); `text` — текст как есть |
| `silent` | `false` | доставить без звука |
| `link_preview` | `false` | показывать превью первой ссылки |

- Текст длиннее 4096 символов отправляется несколькими сообщениями. Разбивка идёт по абзацам,
  строкам или словам, а звук уведомления будет только у первой части.
- Если Telegram не разберёт HTML (например, Claude использовал неподдерживаемый тег),
  сообщение всё равно отправится обычным текстом, без тегов. Claude узнает об этом из ответа инструмента.
- Бот пишет только в чат из настроек: выбрать другой чат Claude не может.

## Установка

Нужен установленный [uv](https://docs.astral.sh/uv/getting-started/installation/)
(`brew install uv` на macOS).

### 1. Создайте бота

1. Откройте [@BotFather](https://t.me/BotFather), отправьте `/newbot` и задайте имя бота.
2. Скопируйте токен вида `123456789:AAE...`.
3. Откройте своего бота по ссылке от BotFather и нажмите **«Запустить»**.
   Пока вы этого не сделали, бот не может написать вам первым.

> [!WARNING]
> Токен — это пароль: с ним любой может писать от имени бота и читать то, что пишут боту.
> Не публикуйте его и не коммитьте в репозитории. Если токен утёк, выпустите новый: `/revoke` в @BotFather.

### 2. Узнайте ID чата

```bash
TELEGRAM_BOT_TOKEN=123456789:AAE... uvx --from git+https://github.com/a-shipilo/telegram-mcp-server telegram-mcp-server chat-id
```

Команда покажет чаты, из которых боту писали за последние 24 часа:

```text
Бот: @my_notify_bot
Чаты, из которых боту писали за последние 24 часа:
  123456789       private     Иван (@ivan)
  -1001234567890  supergroup  Мониторинг
Укажите нужный ID в TELEGRAM_CHAT_ID.
```

Для личных уведомлений нужен ваш личный чат (`private`). Чтобы бот писал в группу,
добавьте его туда и отправьте в группе `/start`. Чтобы бот писал в канал, сделайте его администратором канала.

### 3. Проверьте отправку

```bash
TELEGRAM_BOT_TOKEN=123456789:AAE... TELEGRAM_CHAT_ID=123456789 uvx --from git+https://github.com/a-shipilo/telegram-mcp-server telegram-mcp-server test
```

### 4. Подключите сервер

#### Claude Code

Сервер добавляется на уровне пользователя (`-s user`), чтобы он был доступен во всех проектах
и в задачах по расписанию:

```bash
claude mcp add telegram -s user -e TELEGRAM_BOT_TOKEN=123456789:AAE... -e TELEGRAM_CHAT_ID=123456789 -- uvx --from git+https://github.com/a-shipilo/telegram-mcp-server@v0.1.0 telegram-mcp-server
```

#### Claude Desktop

1. Откройте **Settings → Developer → Edit Config**. Откроется файл `claude_desktop_config.json`.
2. Добавьте сервер в `mcpServers`:

```json
{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/a-shipilo/telegram-mcp-server@v0.1.0",
        "telegram-mcp-server"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "123456789:AAE...",
        "TELEGRAM_CHAT_ID": "123456789"
      }
    }
  }
}
```

3. Полностью перезапустите Claude Desktop. Сервер `telegram` появится в **Settings → Developer**
   со статусом *running*.

`@v0.1.0` фиксирует версию. Чтобы всегда брать последнюю версию из `main`, уберите `@v0.1.0`.
Для обновления добавьте в `args` перед `--from` флаг `--refresh`.

Если в логах `spawn uvx ENOENT`, укажите полный путь к uvx (узнать его: `which uvx`),
например `"command": "/opt/homebrew/bin/uvx"`.

## Уведомления из рутин

Достаточно попросить об уведомлении в тексте задачи:

> …Когда закончишь, отправь мне в Telegram короткий итог: что сделано и что требует моего внимания.
> Если всё в порядке и делать ничего не нужно, отправь сообщение без звука.

**Задачи по расписанию на вашем компьютере** (Claude Desktop, Claude Code) используют ваши локальные
MCP-серверы. Достаточно подключить сервер, как описано выше: в Claude Code — с `-s user`.

**Облачные рутины** ([claude.ai/code](https://code.claude.com/docs/en/routines)) выполняются
в облачном окружении, поэтому локальные настройки туда не попадают:

1. Добавьте в репозиторий, с которым работает рутина, файл `.mcp.json`. Токен в него не пишите:
   Claude Code подставит его из переменных окружения.

   ```json
   {
     "mcpServers": {
       "telegram": {
         "command": "uvx",
         "args": ["--from", "git+https://github.com/a-shipilo/telegram-mcp-server@v0.1.0", "telegram-mcp-server"],
         "env": {
           "TELEGRAM_BOT_TOKEN": "${TELEGRAM_BOT_TOKEN}",
           "TELEGRAM_CHAT_ID": "${TELEGRAM_CHAT_ID}"
         }
       }
     }
   }
   ```

2. В [настройках облачного окружения](https://code.claude.com/docs/en/cloud-environments) задайте переменные
   `TELEGRAM_BOT_TOKEN` и `TELEGRAM_CHAT_ID`.
3. Там же разрешите доступ к `api.telegram.org`: по умолчанию облачное окружение пускает только к
   пакетным репозиториям и распространённым API. Выберите доступ **Custom** и добавьте этот домен.
   Если в окружении нет `uv`, установите его в setup-скрипте: `pip install uv`.

## Настройки

| Переменная | По умолчанию | Описание |
|---|---|---|
| `TELEGRAM_BOT_TOKEN` | — | токен бота от @BotFather, обязательно |
| `TELEGRAM_CHAT_ID` | — | ID чата, куда писать: число (`123456789`, `-1001234567890`) или `@канал`, обязательно |
| `TELEGRAM_API_URL` | `https://api.telegram.org` | адрес Bot API, если у вас [свой сервер Bot API](https://github.com/tdlib/telegram-bot-api) или обратный прокси |

Если Telegram доступен только через прокси, задайте `HTTPS_PROXY`, например `HTTPS_PROXY=http://127.0.0.1:8080`.
Для SOCKS-прокси запускайте сервер с `uvx --with socksio`.

Если сервер запущен без нужных переменных, он всё равно стартует, а `send_message` вернёт
понятную ошибку: так Claude сможет сказать, что именно не настроено.

## Команды

| Команда | Что делает |
|---|---|
| `telegram-mcp-server` | запускает MCP-сервер (stdio) |
| `telegram-mcp-server chat-id` | показывает ID чатов, из которых недавно писали боту |
| `telegram-mcp-server test ["текст"]` | отправляет проверочное сообщение в `TELEGRAM_CHAT_ID` |
| `telegram-mcp-server --version` | версия |

`chat-id` читает последние сообщения через `getUpdates`, но не помечает их прочитанными.
Для уведомлений лучше завести отдельного бота: если бот уже где-то работает, `chat-id` может помешать
его опросу, а при настроенном webhook список чатов недоступен. В этом случае учтите, что ID личного чата
совпадает с вашим ID в Telegram, его можно узнать, например, у [@userinfobot](https://t.me/userinfobot).

## Разработка

```bash
git clone https://github.com/a-shipilo/telegram-mcp-server.git
cd telegram-mcp-server
uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .
```

Локальная отладка в [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npx @modelcontextprotocol/inspector -e TELEGRAM_BOT_TOKEN=... -e TELEGRAM_CHAT_ID=... uv run telegram-mcp-server
```

## Лицензия

[MIT](LICENSE)