# telegram-mcp

Hands Claude the newest image from one Telegram group.

The screenshots are posted by a bot, and the Telegram Bot API never returns a
bot's own messages — so this reads the group with a *user* account over
MTProto (Telethon). That is the only way to see those photos.

## Setup (once)

1. Get an api id and hash from https://my.telegram.org → API development tools.
2. `cp .env.example .env` and fill in `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`,
   and `TELEGRAM_CHAT_ID` (the group's numeric id, negative).
3. Create the environment:

   ```
   python -m venv .venv
   .venv\Scripts\pip install -e .[dev]
   ```

4. Sign in — in a terminal, not through Claude:

   ```
   .venv\Scripts\telegram-mcp-login
   ```

   It asks for your phone number, the code Telegram sends, and your two-factor
   password if you have one, then writes `session/telegram.session`.

   It also lists your dialogs once and prints the group's name back at you. The
   listing is what lets the session resolve a supergroup later -- Telegram turns
   a group into one as soon as a bot joins it -- and the name is your
   confirmation that `TELEGRAM_CHAT_ID` points where you think it does. If it
   cannot find the group, it says so and exits non-zero.

## Install into Claude

```
claude mcp add --scope user telegram -- <abs path>\.venv\Scripts\python -m telegram_mcp.server
```

User scope, so every project gets it.

## Tools

- `get_latest_image()` — the most recent photo in the group, looking back 200
  messages.
- `wait_for_next_image(timeout_seconds=120)` — blocks until a photo newer than
  the moment of the call arrives. Waiting costs no tokens; the process idles on
  a socket. Clamped to 1–240 s to stay inside the MCP client's tool timeout.

Both return the image (JPEG, long edge ≤1568 px) plus a line of text: the path
to the untouched original first, then the message id, timestamp, sender, and the
caption, quoted. Crop that original when the downscale loses fine print.

Only one process can hold the session at a time. A second Claude Code session
calling a tool while the first is mid-call is told to try again in a moment,
rather than being handed a SQLite error.

## Tests

```
.venv\Scripts\python -m pytest
```

No network, no Telegram account needed — Telethon is faked throughout.

## Security

`session/telegram.session` is a full login to your Telegram account. It is
gitignored and never leaves this machine. Anyone holding that file can read
your messages; delete it and re-run the login if you suspect it has been
copied. Credentials live only in `.env` — never in docs, prompts, or tickets.