How do I install Better Telegram MCP?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Better Telegram MCP need an API key?

The publisher lists these environment variables: TELEGRAM_BOT_TOKEN, TELEGRAM_API_ID, TELEGRAM_API_HASH.

What transport does Better Telegram MCP use?

Better Telegram MCP runs locally over stdio.

Better Telegram MCP server

Q: When was Better Telegram MCP last checked?

Last checked 2026-10-28. Telegram for AI agents: messages, chats, media, and contacts in bot and user-account modes.

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

uvx better-telegram-mcp==4.22.0

Credentials from the publisher

TELEGRAM_BOT_TOKEN — Telegram bot token from @BotFather (for bot mode)
TELEGRAM_API_ID — Telegram API ID from my.telegram.org (for user mode)
TELEGRAM_API_HASH — Telegram API hash from my.telegram.org (for user mode)

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1TELEGRAM_BOT_TOKEN=<secret> TELEGRAM_API_ID=<value> TELEGRAM_API_HASH=<secret> claude mcp add io.github.n24q02m-better-telegram-mcp -- uvx better-telegram-mcp==4.22.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.n24q02m-better-telegram-mcp": {4      "command": "uvx",5      "args": [6        "better-telegram-mcp==4.22.0"7      ],8      "env": {9        "TELEGRAM_BOT_TOKEN": "<secret>",10        "TELEGRAM_API_ID": "<value>",11        "TELEGRAM_API_HASH": "<secret>"12      }13    }14  }15}

claude_desktop_config.json

Local · pypiPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

mcp-name: io.github.n24q02m/better-telegram-mcp

Telegram for AI agents: messages, chats, media, and contacts in bot and user-account modes.

Project	Tagline	Tag
agent-chat-plugin	Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor...	Tooling
better-code-review-graph	Knowledge graph for token-efficient code reviews -- semantic search and call-...	MCP
better-drive	2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray	Tooling
better-email-mcp	IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att...	MCP
better-godot-mcp	Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g...	MCP
better-notion-mcp	Markdown-first Notion for AI agents -- pages, databases, blocks, and comments...	MCP
better-semantic-release	Drop-in python-semantic-release fork with built-in release-safety guards (orp...	Tooling
better-telegram-mcp	Telegram for AI agents -- messages, chats, media, and contacts across both bo...	MCP
better-workspace-mcp	Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...	MCP
claude-plugins	Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea...	Marketplace
imagine-mcp	Image and video understanding + generation for AI agents -- across Gemini, Op...

Features
Install
Setup
Smithery
Configuration
HTTP mode
CLI
Tools
Comparison
Security
Build from Source
Trust Model
License

Features

Dual mode -- Bot API (httpx) for bots, MTProto (Telethon) for user accounts
6 tools with action dispatch: message, chat, media, contact, config, help
Auto-detect mode -- Set a bot token for bot mode, or a phone number for user mode
Local CLI auth -- telegram auth handles the bot token, or phone + OTP + 2FA, on the machine that runs the server
Stdio or HTTP -- stdio by default; HTTP with no-auth (loopback only), a single bearer token, or per-user tokens
Tool annotations -- Each tool declares readOnlyHint, destructiveHint, idempotentHint, openWorldHint
MCP Resources -- Documentation available as telegram://docs/* resources
Security hardened -- SSRF protection, path traversal prevention, error sanitization, prompt-injection boundary tags on Telegram content

Install

# Claude Code plugin (stdio, bot mode)
/plugin marketplace add n24q02m/claude-plugins
/plugin install better-telegram-mcp@n24q02m-plugins

# Direct uvx invocation (stdio, bot mode)
claude mcp add telegram -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF -- uvx n24q02m-telegram

# Docker stdio
docker run -i --rm -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF n24q02m/telegram

The package is n24q02m-telegram (formerly better-telegram-mcp; the old package receives one final release then freezes). The MCP Registry id stays io.github.n24q02m/better-telegram-mcp, the Docker image is n24q02m/telegram, and the legacy better-telegram-mcp command is kept as an alias of telegram. Local data moves once from ~/.better-telegram-mcp to ~/.telegram on first start.

Install matrix

Client	Install
Claude Code	`/plugin marketplace add n24q02m/claude-plugins` + `/plugin install better-telegram-mcp@n24q02m-plugins` (stdio bot mode), or `claude mcp add` as in the block above
Cursor / Windsurf / Gemini CLI / any MCP client	`mcpServers` JSON in the client's config: stdio `command`, or `type: "http"` + `url` pointing at a server you run (see HTTP mode)

Install with AI agent -- paste this to your AI coding agent:

Install MCP server telegram following the steps at https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-telegram-mcp/setup-with-agent.md

Setup

Credentials are configured on the machine that runs the server.

Bot mode: set TELEGRAM_BOT_TOKEN in the client config, or save it once:

telegram auth --bot-token 123456:ABC-DEF

User mode: sign in interactively with your phone number. Telegram sends an OTP; a 2FA password is prompted if the account has one. The Telethon session is stored on disk.

telegram auth --phone +15551234567

Check the result with telegram status. The server reads saved credentials at startup, so restart it after telegram auth. Without any credentials the stdio server prints these instructions to stderr and exits with status 1.

Smithery

Also listed on Smithery. Per smithery.yaml, Smithery starts the server over stdio with uvx --python 3.13 n24q02m-telegram and takes no install-time configuration (empty configSchema). Credentials come from the TELEGRAM_BOT_TOKEN env var or a prior telegram auth (see Setup).

Configuration

Settings load from TELEGRAM_-prefixed environment variables (Pydantic Settings). Env vars take precedence over credentials saved by telegram auth.

Variable	Required	Description
`TELEGRAM_BOT_TOKEN`	Bot mode	Bot token from @BotFather (format `123456789:ABCdef...`)
`TELEGRAM_PHONE`	User mode	Phone number in `+<country><number>` form
`TELEGRAM_API_ID` / `TELEGRAM_API_HASH`	No	Override the bundled public API pair
`USE_BUNDLED_TELEGRAM_CLIENT`	No	Set to `false` to require your own API pair
`TELEGRAM_SESSION_NAME`	No	Telethon session file name (default `default`)
`TELEGRAM_DATA_DIR`	No	Session directory (default `~/.telegram`)
`MCP_TRANSPORT`	No	Set to `http` to start in HTTP mode (`--http` or `TRANSPORT_MODE=http` also work)

There is no TELEGRAM_PASSWORD env var: telegram auth prompts for the 2FA password and never stores it in the environment.

HTTP mode

telegram --http serves MCP at /mcp and an unauthenticated GET /health. Settings live in ~/.telegram/config.toml:

[server]
host = "127.0.0.1"   # default; --host overrides
port = 8000          # default; --port overrides
auth = "token"       # "no-auth" | "token" | "multi"
token_hash = "scrypt$..."

`auth`	Who can connect	Credentials used
`no-auth`	Anyone who can reach the port; loopback binds only (a non-loopback host is refused)	The default credentials
`token`	Clients sending `Authorization: Bearer <token>` matching `token_hash`	The default credentials
`multi`	Users listed in `users.toml` (default `~/.telegram/users.toml`), each with their own token	Each user's own namespace

Create a token hash with telegram token hash (it reads the token from stdin or a prompt, never from the command line). In multi mode, add users by editing users.toml and restarting the server:

[users.alice]
token_hash = "scrypt$..."
enabled = true
namespace = "alice"

Then authorize Telegram for that user on the server machine:

telegram auth --phone +15551234567 --user alice

To reach a server on another machine, put it behind a TLS-terminating reverse proxy or a private network and use token or multi auth.

CLI

The telegram console script (installed by uvx / pip; better-telegram-mcp is a legacy alias) starts the MCP server when run without a subcommand. Flags that are not a subcommand are passed through to the server (for example --http, --host, --port).

telegram            # start the MCP server (stdio)
telegram --http     # start in HTTP mode
telegram --version  # print the version

Subcommand	Usage	Description
`auth`	`auth --bot-token <token>` or `auth --phone <+number>`, optional `--user <ns>`	Authorize this machine. Bot mode validates the token; phone mode runs the interactive OTP/2FA flow and stores the Telethon session on disk
`login`	Same arguments as `auth`	Deprecated alias of `auth`
`logout`	`logout [--yes] [--user <ns>]`	Revoke the Telegram session, delete the session file and the saved credentials
`config`	`config status`, `config delete --yes`	Show or delete the saved credential config
`status`	`status`	Show whether credentials are configured
`doctor`	`doctor`	Print environment diagnostics
`token`	`token hash`	Hash a bearer token for `config.toml` / `users.toml`

--user selects the storage namespace (default default, used by stdio and the no-auth / token HTTP modes). Unknown subcommands exit with status 2.

Tools

Tool	Actions	Description
`message`	`send`, `edit`, `delete`, `forward`, `pin`, `react`, `search`, `history`	Send, edit, delete, forward messages. Pin, react, search, browse history
`chat`	`list`, `info`, `create`, `join`, `leave`, `members`, `admin`, `settings`, `topics`	List and manage chats, groups, channels. Members, admin, forum topics
`media`	`send_photo`, `send_file`, `send_voice`, `send_video`, `download`	Send photos, files, voice notes, videos. Download media from messages
`contact`	`list`, `search`, `add`, `block`	List, search, add contacts. Block/unblock users (user mode only)
`config`	`status`, `set`, `cache_clear`	Server status, runtime settings (`message_limit`, `timeout`), cache
`help`	--	Full documentation for any topic

MCP Resources

URI	Content
`telegram://docs/messages`	Message operations reference
`telegram://docs/chats`	Chat management reference
`telegram://docs/media`	Media send/download reference
`telegram://docs/contacts`	Contact management reference
`telegram://stats`	All documentation combined

Comparison

How telegram stacks up against direct competitors in each pillar:

Capability	telegram	chigwell/telegram-mcp	sparfenyuk/mcp-telegram	guangxiangdebizi/telegram-mcp
Bot API mode (bot token)	Yes (httpx)	No	No	Yes
MTProto user-account mode	Yes (Telethon)	Yes	Yes	No
Send / edit / delete messages	Yes	Yes	No (read-only, draft only)	Yes (send only)
Media download from messages	Yes	Yes	Yes	No (send only)
Contact management (add / block)	Yes (user mode)	Yes	Partial (list only)	No
Multi-user HTTP, per-user isolation	Yes (per-user tokens and namespaces)	No	No	No
SSRF protection	Yes (URL validation + DNS-rebinding)	?	?	No
Path-traversal prevention	Yes	Yes (real-path allowed-root)	?	No
Self-hostable	Yes	Yes	Yes	Yes

Security

SSRF Protection -- All URLs validated against internal/private IP ranges, DNS rebinding blocked
Path Traversal Prevention -- File paths validated, sensitive directories blocked
Session File Security -- 600 permissions; the 2FA password is prompted, never stored in env vars
Error Sanitization -- Credentials and bot tokens are never leaked in error messages or logs
Prompt-injection boundaries -- Telegram content returned by tools is wrapped in untrusted-content tags

Build from Source

git clone https://github.com/n24q02m/telegram.git
cd telegram
uv sync
uv run telegram

Trust Model

The project does not operate a hosted Telegram endpoint. The server runs on infrastructure you control, and credentials never leave that machine.

Data	Location	Protection
Saved credentials (bot token / phone)	`~/.telegram/config.json`; `~/.telegram/subs/<ns>/config.json` in `multi` mode	AES-256-GCM with the machine key `~/.telegram/.secret`
Telethon sessions	`~/.telegram/<name>.session`; `~/.telegram/subs/<ns>/` in `multi` mode	File permission 0600
HTTP bearer tokens	`token_hash` in `config.toml` / `users.toml`	Stored only as scrypt hashes

Anyone with access to your OS user account can read these files.

License

Apache-2.0 -- See LICENSE.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Better Telegram MCP?

Does Better Telegram MCP need an API key?

What transport does Better Telegram MCP use?

When was Better Telegram MCP last checked?

Documentation

telegram

Table of contents

Features

Install

Install matrix

Setup

Smithery

Configuration

HTTP mode

CLI

Tools

MCP Resources

Comparison

Security

Build from Source

Trust Model

License