Telegram MCP server for Claude Code, Cursor, Codex and Claude Desktop

Better-TG-CLI includes an MCP server, telegram mcp, that lets an AI client read and search your own Telegram account and, after you approve each send, write to it. It runs on your computer over stdio and talks to Telegram directly; nothing goes through our servers.

1. Install the CLI

brew install thevilfer/tap/better-tg-cli   # macOS or Linux
scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket
scoop install better-tg-cli                 # Windows
npm install -g better-tg-cli                # any OS, Node 20+

The npm package is one file with zero runtime dependencies; Homebrew and Scoop install a standalone binary that needs no Node.

2. Log in once

telegram onboard      # free login key or your own API keys, then a QR code

You scan a QR code in Telegram on your phone. Your login code, 2FA password and session never reach the agent. The session is kept in the macOS Keychain, the Linux Secret Service, Windows DPAPI or 1Password.

3. Add it to your client

claude mcp add telegram -- telegram mcp                     # Claude Code
codex plugin marketplace add TheVilfer/better-tg-cli         # Codex (skill and server)
codex plugin add better-tg-cli@better-tg-cli
gemini extensions install https://github.com/TheVilfer/better-tg-cli   # Gemini CLI

For Claude Desktop, download better-tg-cli.mcpb from the latest release and open it: it needs no Node, npm or Homebrew.

For Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json) and other MCP hosts, use the JSON form with the full path that which telegram prints, because GUI apps may not see your shell PATH:

JSON config

{
  "mcpServers": {
    "telegram": { "command": "/opt/homebrew/bin/telegram", "args": ["mcp"] }
  }
}

# without a global install:
{
  "mcpServers": {
    "telegram": { "command": "npx", "args": ["-y", "better-tg-cli@latest", "mcp"] }
  }
}

The server is listed in the official MCP Registry as io.github.TheVilfer/better-tg-cli.

What the server exposes

telegram_read: read-only commands (inbox, read, search, threads, forum topics, channel comments, contacts), so clients may approve it automatically.
telegram_write: sends, edits, reactions, forwards, bot buttons. It is marked destructive.
telegram_help: a searchable reference of every command and flag.

How writes are approved

After login the profile is in mode ask. Before each write you see the exact action, and it runs only after your yes. Clients that support MCP elicitation ask you in their own dialog, so the model never handles the approval; others pass a one-time code that is bound to that exact text.

telegram write-access off makes the profile read-only. Writing without asking (telegram write-access on --for 1h) needs your confirmation in a terminal or a system dialog. These modes guard against an agent’s mistakes; an agent that runs commands on your computer as you could still read the session, so connect such agents only to chats you trust. Details are in SECURITY.md.

Cloud agents

Cloud agents such as Grok Bot cannot start a program on your computer. Run telegram mcp --http with a bearer token and reach it through a tunnel; the session and the write guard stay on your machine. The README has the steps.