Telegram MCP Server: Complete Setup Guide (2026)

TL;DR + what you actually need

Four things you will keep coming back to if you run the Telegram MCP server seriously:

• Two credentials: TG_APP_ID and TG_API_HASH, both issued free at my.telegram.org. These identify your application to Telegram — they are not your login.
• One auth command, once: npx -y @chaindead/telegram-mcp auth --app-id <id> --api-hash <hash> --phone <number>. Telegram sends a login code to your account; you type it in; a session file lands at ~/.telegram-mcp/session.json. Add --password <2fa> if you use two-factor auth.
• One package: @chaindead/telegram-mcp — a Go binary (MIT) by chaindead, run via npx, Homebrew, a prebuilt release, or go install. Five tools: tg_me, tg_dialogs, tg_dialog, tg_send, tg_read.
• One surprise: tg_send does not send. It saves a draft into the chat’s input box and you press send yourself. That is deliberate, and it is the right call — more below.

Quick install for the copy-paste crowd — Claude Code:

claude mcp add telegram \
  -e TG_APP_ID=YOUR_APP_ID \
  -e TG_API_HASH=YOUR_API_HASH \
  -- npx -y @chaindead/telegram-mcp

Every other client takes the JSON from the install card below. The rest of this guide explains why the auth works the way it does, what each tool returns, and where the Telegram-will-suspend-you edges are.

What Telegram MCP actually does

The server is a stdio process — a local subprocess your MCP client launches — that exposes your Telegram account’s read-and-draft surface as MCP tools. Your agent calls tg_dialogs with the unread filter on, the server fires the corresponding MTProto request against Telegram’s servers using your logged-in session, and the dialog list comes back as a tool response the model can reason over.

What that buys you in practice: an agent that can actually triage your inbox. Ask “summarize my unread Telegram messages and flag anything that needs a reply today” and the model pulls the unread dialogs, reads the recent history in each, and hands you a prioritized digest. Ask it to draft replies and the text appears in each chat’s input box on your phone, waiting for your thumb on the send button. Inbox-zero on a noisy Telegram account drops from twenty minutes to two.

The implementation lives at github.com/chaindead/telegram-mcp — written in Go on top of the gotd/td MTProto library, MIT-licensed, and actively maintained. It is the most-installed Telegram entry in our catalog and a fixture on community lists like awesome-mcp-servers. The server does no AI work itself: agent calls in, Telegram API calls out, nothing stored in between except the session file that keeps you logged in.

One sentence worth engraving before we get to setup: this server is your account, not a bot. Everything else in this guide — the auth flow, the capability ceiling, the draft-only sending, the safety rules — follows from that one design decision.

Auth model: your user account over MTProto, not a bot token

This is the section to read slowly, because it is the key editorial distinction between the two Telegram servers in our catalog — and the thing most people searching “telegram bot mcp” have backwards.

Telegram exposes two completely different APIs, and which one a server uses determines everything it can do:

The chaindead server is firmly in the left column. The consequence cuts both ways: it can summarize a private family group chat a bot could never join silently, and it operates with the full authority — and the full terms-of-service exposure — of your personal account.

Step 1 — get an API ID and API hash

Go to my.telegram.org, log in with your phone number, open API development tools, and create an application (any name works). Telegram issues an api_id (a short integer) and an api_hash (a hex string). These identify your application to MTProto — the same kind of credential every third-party Telegram client carries. They are free, they do not expire, and they should be treated as secrets: anyone with your API pair plus your session file is you.

Step 2 — authenticate once

npx -y @chaindead/telegram-mcp auth \
  --app-id YOUR_APP_ID \
  --api-hash YOUR_API_HASH \
  --phone +15551234567

# If you have 2FA enabled, append:  --password <your-2fa-password>
# To replace an existing session:   --new

Telegram pushes a login code to your other devices (or SMS); you type it into the prompt. On success the command writes a session file to ~/.telegram-mcp/session.json and prints a ready-made MCP config block — a nice touch most servers skip. The session file is what keeps you logged in across restarts, so the phone-code dance happens exactly once. You can relocate it with the TG_SESSION_PATH env var or the --session flag.

Step 3 — env vars at runtime

The serve process needs only two variables — TG_APP_ID and TG_API_HASH — plus the ability to find the session file. It refuses to start with a clear session file not found error if you skip step 2, which is the single most-hit failure on a fresh install (see Troubleshooting). Keep the API hash out of any config file you commit; every client supports env blocks for exactly this reason.

One first-person correction worth admitting: we initially assumed this server wrapped the Bot API because the catalog short-description mentions “telegram bot.” It does not. There is no bot token anywhere in the flow, and if you came here with a @BotFather token in hand, you want the Telegram Communicator server instead — covered in Alternatives below.

Install (every client)

The server is stdio-only — your MCP client launches it as a subprocess. Four distribution channels, all shipping the same Go binary:

• npx (recommended): npx -y @chaindead/telegram-mcp — works on macOS, Linux, and Windows, always pulls the latest release.
• Homebrew: brew install chaindead/tap/telegram-mcp (upgrade with brew upgrade).
• Prebuilt binaries: tarballs and zips for macOS (Intel/Apple Silicon), Linux (x86_64/ARM64), and Windows on the releases page.
• From source: go install github.com/chaindead/telegram-mcp@latest (requires a current Go toolchain).

The install panel below pulls its config from the canonical /servers/telegram catalog entry, so it stays in sync with the package name and env-var shape. Pick your client, copy, paste, fill in the two values, restart.

One-line install · Telegram

Open server page

Install

Cursor

One-click install

VS Code

One-click install

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Client-specific notes that don’t fit the panel:

• Claude Code: the one-liner from the TL;DR. Add --scope project to register in the repo’s .mcp.json instead of your user config. Full flag reference at /clients/claude-code.
• Claude Desktop: config lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\ on Windows. If you installed the binary rather than using npx, the README’s example adds PATH and HOME to the env block — Claude Desktop launches servers with a minimal environment, and without HOME the server can’t find ~/.telegram-mcp/session.json.
• Cursor: paste the mcpServers JSON into ~/.cursor/mcp.json; the README ships a Cursor-specific example with just the two TG_* vars.
• VS Code: one extra env var. VS Code’s MCP support rejects tool schemas in JSON Schema Draft 2020-12 (the server’s default), so set TG_SCHEMA_VERSION=https://json-schema.org/draft-07/schema# in the env block. The maintainer added this override after VS Code users hit silent tool-registration failures.
• Sanity check before any client: run the server once with the --dry flag: npx -y @chaindead/telegram-mcp --dry (with the env vars exported). It exercises tg_me and the dialog tools against your real session and logs each check — far faster than debugging through a client’s MCP logs.

Browse every supported client and its config path at mcp.directory/clients.

Tools walkthrough

Five tools, small by design. Names and descriptions below are verbatim from the server’s tool registration, with what the source actually does behind each.

tg_me — account info

Returns the logged-in account’s profile: who the agent is acting as. Agents call it once at the start of a session to ground themselves; you call it via --dry to confirm auth works.

tg_dialogs — list chats, channels, users

The workhorse. Lists your dialogs — DMs, groups, channels — with an unread filter and pagination via an offset argument. Every inbox-triage workflow starts here: “what’s unread?” maps to one tg_dialogs call with the filter on.

tg_dialog — read a conversation’s messages

Retrieves message history for one dialog, addressed by name. Usernames work directly for public entities; for private chats and channels the server uses an internal ID syntax — cht[1234567] for chats, chn[1234567:hash] for channels — which tg_dialogs returns, so the agent chains the two tools naturally. This is the tool that makes “summarize the last 50 messages in the infra channel” a one-prompt job.

tg_send — draft a message (read this one twice)

Registered with the description “Send draft message to dialog”, and the word draft is load-bearing. The implementation calls MTProto’s messages.saveDraft — the text appears in the target chat’s input box, synced to all your devices, unsent. Nothing the agent does through this server posts a message under your name.

The community keeps asking for direct sending — issue #14 (“Why it sends only draft messages?”) stays open, and multiple PRs propose a separate direct-send tool. As of this writing, mainline remains draft-only. Our take: that is the correct default for a server wielding your personal account. An LLM that misreads context and drafts an awkward reply costs you a delete keystroke; one that sends it costs you an apology. Review-then-send is the feature.

tg_read — mark a dialog as read

Clears the unread state on a dialog. Pairs with the triage flow: summarize unread, draft replies where needed, mark the rest read. The only other write-shaped tool in the set, and the worst it can do is clear a badge.

Recipes

Five workflows where this server earns its install. All assume valid auth and the server registered in your client.

Recipe 1 — Morning inbox triage

Prompt: “Check my unread Telegram dialogs. Summarize each in one line, ordered by how urgently it needs a reply. Flag anything from my boss or anything with a question directed at me.” The agent calls tg_dialogs with the unread filter, then tg_dialog on each hit to read context. Output: a ranked digest instead of fourteen badge counts.

Recipe 2 — Draft replies in bulk, send by hand

Prompt: “For each unread chat with an unanswered question, draft a reply in my usual tone — short, no emoji. Save each as a draft and list which chats now have drafts waiting.” The agent reads, writes via tg_send, and you walk through Telegram on your phone tapping send (or editing first). This is the single best workflow the draft-only model enables: bulk-process the typing, keep the judgment.

Recipe 3 — Channel digest

Prompt: “Read the last 100 messages in the [team-infra] channel and give me decisions made, open questions, and anything that mentions me.” One tg_dialog call, one summary. Works on private channels a bot could never be added to quietly — the user-account advantage in its purest form.

Recipe 4 — Cross-chat search by reading, not API search

The server has no server-side search tool, so phrase the task as targeted reading: “Check my dialogs with Alice, Bob, and the project group for any message about the contract deadline in the last week. Quote the relevant lines.” The agent pulls history from each named dialog and filters in-context. Works well up to a handful of chats; for archive-wide search, use Telegram’s own search first and hand the agent the chat name.

Recipe 5 — Inbox-zero sweep

Prompt: “Go through my unread dialogs. Anything that is purely informational — channels, notifications, group chatter that doesn’t involve me — mark as read. Leave anything needing a human decision unread and list those.” tg_dialogs → tg_dialog → tg_read, looped. The agent clears the noise; the signal stays badged.

Limits + account safety

Know the edges before you wire this to an always-on agent.

• No direct sending. Covered above — drafts only. If your use case is genuinely notification-style sending (CI alerts, agent status pings), that is Bot API territory; see Alternatives.
• Text in, text out. The tools read and draft plain text. No media download, no file upload, no stickers, no voice messages.
• No server-side search. Filtering happens in the agent’s context window after tg_dialog returns history. Big channels with long histories mean big tool responses — scope your prompts to named chats and bounded windows.
• Telegram’s flood-wait limits apply. MTProto rate-limits aggressive clients with FLOOD_WAIT errors — back-off demands that can run seconds to hours. A reasonable agent reading a few dozen dialogs will never see one; a loop hammering history requests across hundreds of dialogs will. Tell the agent to batch, not iterate.
• The session file is a credential. ~/.telegram-mcp/session.json plus your API pair equals full account access. Keep it out of dotfile repos and shared machines, and revoke the session from Telegram’s Settings → Devices if a machine is compromised.
• Terms of service are real. The README leads with a warning to read Telegram’s API ToS because misuse can get the account suspended — and with a user-account server, “the account” is your account. Reading your own messages and saving drafts is ordinary client behavior. Spam-shaped automation is not. This is the contrarian voice worth hearing before you install: the same access that makes this server powerful makes a careless agent expensive.

Cost: zero. MIT server, free API credentials, no hosted tier, no metering. It sits near the top of our best free MCP servers list because the only thing it consumes is your own rate-limit headroom.

Troubleshooting

Alternatives: when a bot is the right answer

The catalog has a second Telegram server built on the other API, and the choice between them is clean.

Telegram Communicatorqpd-v

1-Click Ready

Enable real-time, secure chat via telegram bots. Telegram Communicator supports asynchronous messaging & private telegra

communication8741

Telegram Communicator wraps the Bot API: you create a bot with @BotFather, set TELEGRAM_TOKEN and CHAT_ID, and the agent talks through the bot to one chat. Pick it when:

• You want real sending. Bots send messages directly — no draft step — because a bot misfiring is low-stakes in a way your personal account is not.
• The use case is notifications: an agent pinging you when a long task finishes, CI alerts, approval requests mid-run.
• You want a disposable identity. Token leaks? Revoke the bot. Your account never enters the blast radius.

Pick chaindead’s server when the job is reading and triaging your Telegram — bots cannot see your DMs, your private groups, or anything they weren’t explicitly added to. Plenty of people run both: the user-account server for inbox work, a bot for agent-to-you notifications. MCP clients handle multiple registered servers without fuss.

If you’re building out a broader agent toolkit, this server pairs naturally with the rest of our awesome MCP servers roundup; and if you liked this guide’s format, the Datadog MCP deep-dive applies the same treatment to observability.

FAQ

Sources

• Primary — repository, README, and tool source (serve.go, draft.go, auth.go): github.com/chaindead/telegram-mcp (MIT, Go, built on gotd/td)
• Primary — npm package: npmjs.com/package/@chaindead/telegram-mcp
• Primary — Telegram API credentials: my.telegram.org · API Terms of Service: core.telegram.org/api/terms
• Community — draft-only sending discussion: GitHub issue #14 · VS Code schema issues #6 and #11
• Community — Show HN setup walkthrough thread: news.ycombinator.com/item?id=46411314
• Canonical MCP.Directory entries: /servers/telegram · /servers/telegram-communicator

Note on community embeds: we could not verify a first-party X/Twitter post from the maintainer about this server, so this guide ships without a tweet embed rather than attributing one we can’t source.