telegram-mcp-tdlib

# Telegram MCP Server

[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![CI](https://github.com/tolboy/telegram-mcp-tdlib/actions/workflows/ci.yml/badge.svg)](https://github.com/tolboy/telegram-mcp-tdlib/actions/workflows/ci.yml)
[![Security](https://github.com/tolboy/telegram-mcp-tdlib/actions/workflows/security.yml/badge.svg)](https://github.com/tolboy/telegram-mcp-tdlib/actions/workflows/security.yml)
[![Latest release](https://img.shields.io/github/v/release/tolboy/telegram-mcp-tdlib)](https://github.com/tolboy/telegram-mcp-tdlib/releases/latest)

**Telegram MCP for real accounts — safe by default, TDLib-powered, production-ready.**

A local-first [Model Context Protocol](https://modelcontextprotocol.io/) server that gives
an AI agent real Telegram-account access without handing it the keys to your account. It
starts read-only, hides write tools until you opt in, and runs over **STDIO** for desktop
clients or **Streamable HTTP** at `/mcp` for managed deployments.

### Why this one?

- **Safe by default** — boots in read-only mode with a small `inbox`/`reader` profile;
  write and quota-consuming tools are *hidden from the model*, not merely blocked, until you
  turn them on.
- **Human approval that does not depend on your client** — destructive tools ask a person
  first: through the MCP host where elicitation exists, otherwise on a single-use loopback
  page this server hosts. Either way the question leaves and the answer returns outside the
  model's turn, so an injected instruction can make the model *request* a ban, not approve one.
- **Sends an agent can retry** — an `idempotency_key` turns a lost response into a stored
  receipt instead of a duplicate message; an unconfirmed send is reported as `UNKNOWN`,
  never silently resent.
- **Real user accounts, not just bots** — built on **TDLib** (via tdlight-java), so an agent
  can read and act on your actual account, not only a Bot API subset.
- **Isolated multi-account** — each account gets its own session, mandatory selection, and
  scoped API keys; reads never fan out across accounts.
- **Two transports** — STDIO for Claude Desktop / Cursor / VS Code / Codex, Streamable HTTP
  for a managed service.
- **No JDK to install** — runtime-inclusive release bundles for Windows, Linux x64/ARM64, and
  Apple-silicon macOS, with checksums, an SBOM, and signed container digests.

![Telegram MCP — read-only inbox summary in an AI client](docs/assets/hero.svg)

> The image is an illustrative mockup; a real screencast is on the way.

## Safe first run

Runtime-inclusive releases need no JDK, Gradle, Git, Python, or Node.js. Use a test account
for your first run if you can.

**1. Install** (macOS Apple silicon / Linux with Homebrew):

```bash
brew install --formula https://github.com/tolboy/telegram-mcp-tdlib/releases/latest/download/telegram-mcp.rb
```

Windows with Scoop:

```powershell
scoop install https://github.com/tolboy/telegram-mcp-tdlib/releases/latest/download/telegram-mcp.json
```

**2. Log in** with a QR scan — the one-time code never touches your shell history:

```bash
telegram-mcp auth --method qr
```

**3. Check the session** is ready — this reads local state and starts no server:

```bash
telegram-mcp session doctor
```

Do not run `serve --transport stdio` yourself to try it out. With STDIO your AI
client starts the server and owns its lifetime; a copy you launched in a terminal
holds the TDLib session, and the client's own copy then exits with code 2 because
it cannot lock `td.binlog`. Give the command to the client instead (below) and let
it do the starting.

Then try a first prompt that cannot change anything:

> “Summarize my last 20 conversations. Do not send or modify anything.”

In this mode write and quota-consuming tools are absent from the tool list entirely, so the
model has nothing destructive to call. Switch to `MCP_READ_ONLY=false` only after you have
reviewed the surface. When you do, add `MCP_DESTRUCTIVE_APPROVAL=auto` so deletes, bans and
leaves wait for your answer through host elicitation where available, or through the
server's loopback page otherwise, rather than trusting the model's own `"confirmed": true`.

## Connect your client

Generate the entry instead of transcribing one — it fills in the key your client
actually expects and pins the version it was generated from:

```bash
telegram-mcp config --client claude
```

`--client claude-code|cursor|vscode|codex` switches target — Codex gets TOML, VS
Code gets the `servers` key it actually reads, Claude Code gets the explicit
transport `type`. `--writes` enables write tools and the approval prompt that
guards the destructive ones — pair it with a write-capable
`--profile inbox|community-admin|all`, since the default `reader` surface hides
write tools before read-only mode is consulted. `--docker default` emits a container entry with a
pinned image, and `--http default` emits the shared-daemon entry for Claude Code,
Cursor, VS Code, or Codex. Claude Desktop does not read remote servers from
`claude_desktop_config.json`; add a network-reachable remote endpoint under
Settings → Connectors instead. Claude remote connectors do not accept the
generator's custom API-key header, so this server must be exposed over HTTPS
with `MCP_AUTH_MODE=oauth`. The generator therefore rejects
`--client claude --http`.

STDIO is the low-friction path for desktop clients. The generated entry looks like:

```json
{
  "mcpServers": {
    "telegram": {
      "command": "telegram-mcp",
      "args": ["serve", "--transport", "stdio"],
      "env": {
        "TDLIB_API_ID": "123456",
        "TDLIB_API_HASH_FILE": "/absolute/path/to/telegram-api-hash",
        "MCP_TOOL_PROFILE": "inbox",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}
```

- **Claude Desktop** — add the block above to `claude_desktop_config.json`, then quit the app
  from the tray and start it again. Use Settings → Developer → Edit Config to open the file:
  it points at the right copy for your build. Editing `%APPDATA%\Claude` by hand works only
  for the installer build — the Microsoft Store build is packaged as MSIX and keeps its config
  in `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\` instead.
- **Cursor** — add it to `~/.cursor/mcp.json` (or Settings → MCP → Add).
- **VS Code** — use `.vscode/mcp.json`; VS Code names the top-level key `servers`
  instead of `mcpServers` and requires an explicit `"type": "stdio"` or
  `"type": "http"`.

To share one local process across clients, use `telegram-mcp daemon start` and
`telegram-mcp daemon attach --client cursor` (or `codex`, `vscode`, `claude-code`).
See [managed local daemon](docs/LOCAL_DAEMON.md) for status, stop and onboarding.

For a managed HTTP deployment instead of STDIO:

```bash
docker run --rm -p 127.0.0.1:8080:8080 \
  -e TDLIB_API_ID -e TDLIB_API_HASH -e MCP_API_KEY \
  ghcr.io/tolboy/telegram-mcp-tdlib:latest
```

See [CLI and STDIO](docs/CLI_AND_STDIO.md), [interactive authentication](docs/INTERACTIVE_AUTH.md), and [client compatibility](docs/MCP_CLIENT_COMPATIBILITY.md) for exact platform/client variants.

## Recipes

For reusable agent instructions, install the free
[Telegram Inbox Assistant skill](skills/telegram-inbox-assistant/SKILL.md).
Requires server 1.17.2 or later. Shared-daemon users of Claude Desktop can use
the optional [tools bridge](docs/CLAUDE_DESKTOP_BRIDGE.md), included in runtime
packages with its Python dependency instructions.
Its [setup guide](skills/telegram-inbox-assistant/SETUP.md) includes client
configuration templates and explains the separately required local server
and Telegram authorization. The skill summarizes and searches in read-only mode.

Copy-paste configurations and prompts for real tasks, each with the smallest
tool surface that can do the job:
[summarize your inbox](docs/recipes/summarize-inbox.md),
[find a lost message](docs/recipes/find-lost-message.md),
[research public groups](docs/recipes/research-public-groups.md),
[read-only community health check](docs/recipes/community-review-readonly.md),
and [draft replies without sending](docs/recipes/safe-draft-reply.md) —
index in [docs/recipes](docs/recipes/README.md).

## How it compares

Most Telegram MCP servers wrap the Bot API or a Telethon user session and expose every
capability to the model at once. This project optimizes for connecting an agent to a **real
account you care about**, safely:

| Dimension | This server | Typical Telethon / Bot-API MCP servers |
|---|---|---|
| Account access | Real user account via TDLib (tdlight-java) | Often bot-only, or a single Telethon user session |
| Default posture | Read-only; write/quota tools **hidden** until enabled | Usually all tools exposed from the start |
| Multi-account | Isolated sessions, mandatory selection, scoped keys, **no cross-account read fan-out** | Single account, or implicit fan-out |
| Transports | STDIO **and** Streamable HTTP `/mcp` | Usually STDIO only |
| Guardrails | Confirmation gating, audit log, anti-spam limits, chat allow-list, untrusted-content marking | Minimal |
| Distribution | Signed runtime bundles (no JDK), SBOM + provenance, GHCR image | Source install via pip/npx |

A fuller architectural comparison (TDLib vs Telethon vs Bot API, and why "hidden,
not blocked" matters) is in [docs/COMPARISON.md](docs/COMPARISON.md). The detailed,
dated benchmark against the leading public servers — including features
deliberately declined (raw MTProto escape hatch, ownership transfer, bulk contact export) —
is in [PUBLIC_BENCHMARK_AND_ROADMAP.md](docs/PUBLIC_BENCHMARK_AND_ROADMAP.md).

## Tool profiles

You don't expose 115 tools on day one. `MCP_TOOL_PROFILE` narrows the advertised surface
*before a client ever sees it*, without weakening account scoping, read-only mode,
confirmation, audit, or anti-spam:

| Profile | Surface |
|---|---|
| `reader` | Always non-mutating — safe for a first look |
| `inbox` | Personal messages, drafts, media, contact