{
  "markdown": "# Telegram MCP Server\n\n[![npm](https://img.shields.io/npm/v/@overpod/mcp-telegram)](https://www.npmjs.com/package/@overpod/mcp-telegram)\n[![npm downloads](https://img.shields.io/npm/dm/@overpod/mcp-telegram)](https://www.npmjs.com/package/@overpod/mcp-telegram)\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.29-green.svg)](https://modelcontextprotocol.io/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![mcp-telegram MCP server](https://glama.ai/mcp/servers/overpod/mcp-telegram/badges/score.svg)](https://glama.ai/mcp/servers/overpod/mcp-telegram)\n\n> **[📖 Documentation](https://mcp-telegram.github.io/mcp-telegram/)** · **[☁️ Cloud version](https://mcp-telegram.com)** — connect Telegram to Claude.ai or ChatGPT in 30 seconds with QR code, no API keys needed.\n\n<p align=\"center\">\n  <img src=\"assets/demo.gif\" alt=\"MCP Telegram demo — connect and summarize chats in Claude\" width=\"700\">\n</p>\n\n**Telegram MCP Server** — a Model Context Protocol server that connects AI assistants like Claude and ChatGPT to Telegram via the MTProto protocol. Unlike bots, this runs as a **userbot** -- it operates under your personal Telegram account using [GramJS](https://github.com/nicedoc/gramjs), giving full access to your chats, contacts, and message history.\n\n## Features\n\n- **Comprehensive tool coverage** -- the most full-featured Telegram MCP server available\n- **MTProto protocol** -- direct Telegram API access, not the limited Bot API\n- **Userbot** -- operates as your personal account, not a bot\n- **Full-featured** -- messaging, reactions, polls, scheduled messages, stickers, media, contacts, and more\n- **Forum Topics** -- list topics, read per-topic messages, send to specific topics, per-topic unread counts\n- **Stickers** -- search sticker sets, browse installed/recent stickers, send stickers to any chat\n- **Account & profile management** -- update profile, set emoji status, birthday, personal channel, profile photo, manage privacy settings, sessions, auto-delete timers\n- **Chat folders** -- create, edit, delete and reorder folders, toggle folder tags, read suggested folders (v1.33.0)\n- **Global privacy** -- read and set account-wide privacy settings (v1.33.0)\n- **Global search** -- search messages across all chats at once\n- **Real-time polling** -- fetch updates via stateless cursors; agent owns `{pts, qts, date}` state\n- **Inline bots & buttons** -- query inline bots, send results, press callback buttons\n- **Stories** -- read stories from peers, get story view stats; publish/edit/delete stories, react, pin, stealth mode, archive, report (v1.30.0)\n- **Discussion** -- get discussion-group info for channel posts with comments, list groups eligible for discussion (v1.30.0)\n- **Read Receipts** -- who read a message in a small group, when your private message was read (v1.30.0)\n- **Admin controls** -- toggle channel signatures, anti-spam, forum mode, prehistory; approve join requests\n- **Stats** -- channel and supergroup analytics (GetBroadcastStats / GetMegagroupStats)\n- **Boosts & Business** -- boost status, boosters list, Telegram Business chat links CRUD, work hours, location, greeting/away/intro messages\n- **Star gifts** -- browse available and saved gifts, save/convert gifts, manage Stars balance and subscriptions (opt-in via `MCP_TELEGRAM_ENABLE_STARS=1`, v1.34.0)\n- **Shared daemon** -- one background process serves multiple MCP clients over a single Telegram session; see the [shared-daemon guide](https://mcp-telegram.github.io/mcp-telegram/guides/shared-daemon) (v1.38.0)\n- **QR code login** -- authenticate by scanning a QR code in the Telegram app\n- **Session persistence** -- login once, stay connected across restarts\n- **Human-readable output** -- sender names are resolved, not just numeric IDs\n- **Works with any MCP client** -- Claude Code, Claude Desktop, ChatGPT, Cursor, VS Code, Mastra, etc.\n\n## Prerequisites\n\n- **Node.js** 18 or later\n- **Telegram API credentials** -- `API_ID` and `API_HASH` from [my.telegram.org](https://my.telegram.org)\n\n## Quick Start\n\n### 1. Get Telegram API credentials\n\n1. Go to [my.telegram.org](https://my.telegram.org) and log in with your phone number.\n2. Navigate to **API development tools**.\n3. Create a new application (any name and platform).\n4. Copy the **App api_id** and **App api_hash**.\n\n### 2. Login\n\n```bash\nTELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH npx @overpod/mcp-telegram login\n```\n\nA QR code will appear in the terminal. Open Telegram on your phone, go to **Settings > Devices > Link Desktop Device**, and scan the code. The session is saved to `~/.mcp-telegram/session` and reused automatically.\n\n> **Custom session path:** set `TELEGRAM_SESSION_PATH=/path/to/session` to store the session file elsewhere.\n\n> **Two-step verification (2FA):** if your account has a cloud password enabled, scanning the QR code is not enough — Telegram also requires the password. Provide it via `TELEGRAM_2FA_PASSWORD` so the login can complete:\n>\n> ```bash\n> TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH TELEGRAM_2FA_PASSWORD=YOUR_PASSWORD npx @overpod/mcp-telegram login\n> ```\n>\n> The password is only used locally to answer Telegram's SRP challenge and is never persisted.\n\n### 3. Add to Claude\n\n```bash\nclaude mcp add telegram -s user \\\n  -e TELEGRAM_API_ID=YOUR_ID \\\n  -e TELEGRAM_API_HASH=YOUR_HASH \\\n  -- npx @overpod/mcp-telegram\n```\n\nThat's it! Ask Claude to run `telegram-status` to verify.\n\n### Multiple Accounts\n\nUse `TELEGRAM_SESSION_PATH` to run separate Telegram accounts side by side:\n\n```bash\n# Login each account with a unique session path\nTELEGRAM_API_ID=ID1 TELEGRAM_API_HASH=HASH1 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work npx @overpod/mcp-telegram login\nTELEGRAM_API_ID=ID2 TELEGRAM_API_HASH=HASH2 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal npx @overpod/mcp-telegram login\n```\n\nThen add each as a separate MCP server:\n\n```bash\nclaude mcp add telegram-work -s user \\\n  -e TELEGRAM_API_ID=ID1 \\\n  -e TELEGRAM_API_HASH=HASH1 \\\n  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work \\\n  -- npx @overpod/mcp-telegram\n\nclaude mcp add telegram-personal -s user \\\n  -e TELEGRAM_API_ID=ID2 \\\n  -e TELEGRAM_API_HASH=HASH2 \\\n  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal \\\n  -- npx @overpod/mcp-telegram\n```\n\nEach account gets its own session file — no conflicts.\n\n### Multiple agents / concurrent clients (shared daemon)\n\nThe opposite of multiple accounts: **one** account driven by **many** clients at once — several Claude Code windows, parallel sub-agents, or multiple IDEs. Normally each process opens the same session and they evict one another with `AUTH_KEY_DUPLICATED`. Serve mode fixes this.\n\nRun a single persistent **daemon** that owns the one Telegram connection. Every other process auto-detects the daemon (via a PID lock) and becomes a thin client that proxies tool calls to it over a local Unix socket:\n\n```bash\n# On the host, once: start the daemon (owns the connection, no stdio)\nTELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH mcp-telegram serve\n# (or set MCP_TELEGRAM_DAEMON=1 instead of the `serve` argument)\n```\n\nThen point each MCP client at the same install with the same `TELEGRAM_SESSION_PATH` — no `serve` argument. They connect to the daemon automatically; closing any client never drops the shared connection. Credentials are only required by the daemon (the owner), so client commands can omit `TELEGRAM_API_ID`/`TELEGRAM_API_HASH` and keep them where the daemon runs.\n\nSee the **[shared daemon guide](docs/guides/shared-daemon.md)** for a systemd unit and SSH usage.\n\n### Proxy Support\n\nIf Telegram is blocked or you're running in a containerized environment (Docker, K3s), use a SOCKS5 or MTProxy:\n\n```bash\n# SOCKS5 proxy\nTELEGRAM_PROXY_IP=127.0.0.1 \\\nTELEGRAM_PROXY_PORT=10808 \\\nnpx @overpod/mcp-telegram\n\n# MTProxy\nTELEGRAM_PROXY_IP=proxy.example.com \\\nTELEGRAM_PROXY_PORT=443 \\\nTELEGRAM_PROXY_SECRET=ee00000000000000000000000000000000 \\\nnpx @overpod/mcp-telegram\n```\n\n| Variable | Description |\n|----------|-------------|\n| `TELEGRAM_PROXY_IP` | Proxy server address |\n| `TELEGRAM_PROXY_PORT` | Proxy server port |\n| `TELEGRAM_PROXY_SOCKS_TYPE` | `4` or `5` (default: `5`) |\n| `TELEGRAM_PROXY_SECRET` | MTProxy secret (enables MTProxy mode) |\n| `TELEGRAM_PROXY_USERNAME` | Optional proxy auth |\n| `TELEGRAM_PROXY_PASSWORD` | Optional proxy auth |\n\n### Connecting via WSS (port 443)\n\nIf your VPS or hosting IP is reachable on outbound port `443` but not the default MTProto port `80` (some cloud providers ban port `80` on Telegram DC IP ranges as anti-abuse policy), set:\n\n```bash\nTELEGRAM_USE_WSS=true npx @overpod/mcp-telegram\n```\n\n| Variable | Description |\n|----------|-------------|\n| `TELEGRAM_USE_WSS` | When `true`, gramJS uses port `443` instead of `80` for the MTProto TCPFull transport. Default: `false`. Cannot be combined with `TELEGRAM_PROXY_*` (gramJS limitation) — if both are set, `useWSS` is ignored and the proxy takes precedence (a warning is logged). |\n\n## Installation Options\n\n### npx (recommended, zero install)\n\nNo need to clone or install anything. Just use `npx @overpod/mcp-telegram`.\n\n### Global install\n\n```bash\nnpm install -g @overpod/mcp-telegram\nmcp-telegram          # run server\nmcp-telegram login    # QR login\n```\n\n### Pre-built binary (no runtime needed)\n\nDownload from [Releases](https://github.com/mcp-telegram/mcp-telegram/releases) — standalone single-file binaries, zero dependencies:\n\n| Platform | Server | Login CLI |\n|----------|--------|-----------|\n| Linux x64 | `mcp-telegram-linux-x64` | `mcp-telegram-login-linux-x64` |\n| Linux ARM64 | `mcp-telegram-linux-arm64` | `mcp-telegram-login-linux-arm64` |\n| macOS x64 | `mcp-telegram-darwin-x64` | `mcp-telegram-login-darwin-x64` |\n| macOS ARM64 | `mcp-telegram-darwin-arm64` | `mcp-telegram-login-darwin-arm64` |\n| Windows x64 | `mcp-telegram-windows-x64.exe` | `mcp-telegram-login-windows-x64.exe` |\n\n```bash\n# Download (example for Linux x64)\ncurl -L -o mcp-telegram https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-linux-x64\ncurl -L -o mcp-telegram-login https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-login-linux-x64\nchmod +x mcp-telegram mcp-telegram-login\n\n# Login\nTELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH ./mcp-telegram-login\n\n# Run\n./mcp-telegram\n```\n\n### From source\n\n```bash\ngit clone https://github.com/mcp-telegram/mcp-telegram.git\ncd mcp-telegram\nnpm install && npm run build\n```\n\n### Docker\n\n```bash\ndocker build -t mcp-telegram https://github.com/mcp-telegram/mcp-telegram.git\n```\n\nLogin (interactive terminal required):\n\n```bash\ndocker run -it --rm \\\n  -e TELEGRAM_API_ID=YOUR_ID \\\n  -e TELEGRAM_API_HASH=YOUR_HASH \\\n  -v ~/.mcp-telegram:/root/.mcp-telegram \\\n  --entrypoint node mcp-telegram dist/qr-login-cli.js\n```\n\nRun the MCP server:\n\n```bash\ndocker run -i --rm \\\n  -e TELEGRAM_API_ID=YOUR_ID \\\n  -e TELEGRAM_API_HASH=YOUR_HASH \\\n  -v ~/.mcp-telegram:/root/.mcp-telegram \\\n  mcp-telegram\n```\n\n> **Note**: Login must be done once via terminal. After that, the session is persisted in `~/.mcp-telegram` and reused automatically.\n\n## Usage with MCP Clients\n\n### Claude Code (CLI)\n\n```bash\nclaude mcp add telegram -s user \\\n  -e TELEGRAM_API_ID=YOUR_ID \\\n  -e TELEGRAM_API_HASH=YOUR_HASH \\\n  -- npx @overpod/mcp-telegram\n```\n\n### Claude Desktop\n\n1. Open your config file:\n   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n2. Add the Telegram server:\n\n```json\n{\n  \"mcpServers\": {\n    \"telegram\": {\n      \"command\": \"npx\",\n      \"args\": [\"@overpod/mcp-telegram\"],\n      \"env\": {\n        \"TELEGRAM_API_ID\": \"YOUR_ID\",\n        \"TELEGRAM_API_HASH\": \"YOUR_HASH\"\n      }\n    }\n  }\n}\n```\n\n3. Restart Claude Desktop.\n\n4. Ask Claude: **\"Run telegram-login\"** -- a QR code will appear. If the image is not visible, it's also saved to `~/.mcp-telegram/qr-login.png`. Scan it in Telegram (**Settings > Devices > Link Desktop Device**).\n\n5. Ask Claude: **\"Run telegram-status\"** to verify the connection.\n\n> **Note**: No terminal required! Login works entirely through Claude Desktop.\n\n### Claude Desktop (Binary)\n\nSame setup, but using the pre-built binary instead of npx:\n\n```json\n{\n  \"mcpServers\": {\n    \"telegram\": {\n      \"command\": \"/path/to/mcp-telegram\",\n      \"env\": {\n        \"TELEGRAM_API_ID\": \"YOUR_ID\",\n        \"TELEGRAM_API_HASH\": \"YOUR_HASH\"\n      }\n    }\n  }\n}\n```\n\n### Claude Desktop (Docker)\n\n1. Login via terminal first (see [Docker](#docker) section above).\n\n2. Add to your config file:\n\n```json\n{\n  \"mcpServers\": {\n    \"telegram\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\",\n        \"-e\", \"TELEGRAM_API_ID=YOUR_ID\",\n        \"-e\", \"TELEGRAM_API_HASH=YOUR_HASH\",\n        \"-v\", \"~/.mcp-telegram:/root/.mcp-telegram\",\n        \"mcp-telegram\"\n      ]\n    }\n  }\n}\n```\n\n3. Restart Claude Desktop. Ask Claude: **\"Run telegram-status\"** to verify.\n\n### Cursor / VS Code\n\nAdd the same JSON config above to your MCP settings (Cursor Settings > MCP, or VS Code MCP config).\n\n### Mastra\n\n```typescript\nimport { MCPClient } from \"@mastra/mcp\";\n\nconst telegramMcp = new MCPClient({\n  id: \"telegram-mcp\",\n  servers: {\n    telegram: {\n      command: \"npx\",\n      args: [\"@overpod/mcp-telegram\"],\n      env: {\n        TELEGRAM_API_ID: process.env.TELEGRAM_API_ID!,\n        TELEGRAM_API_HASH: process.env.TELEGRAM_API_HASH!,\n      },\n    },\n  },\n});\n```\n\n## Tools\n\nAll tools are auto-discoverable via MCP — your AI client will see the full list with parameters and descriptions when connected.\n\n| Category | Tools |\n|----------|-------|\n| **Auth** | `telegram-status`, `telegram-login`, `telegram-logout` |\n| **Messaging** | `telegram-send-message` (incl. `quoteText` for verbatim reply quotes and Premium message `effect`), `telegram-edit-message`, `telegram-delete-message`, `telegram-forward-message`, `telegram-send-scheduled`, `telegram-send-typing`, `telegram-translate-message`, `telegram-get-message-link` |\n| **Scheduled** | `telegram-get-scheduled`, `telegram-delete-scheduled` |\n| **Reading** | `telegram-list-chats`, `telegram-read-messages`, `telegram-search-messages`, `telegram-search-global`, `telegram-search-chats`, `telegram-get-unread`, `telegram-mark-as-read`, `telegram-get-replies`, `telegram-get-unread-mentions`, `telegram-get-unread-reactions`, `telegram-get-saved-dialogs` |\n| **Drafts** | `telegram-save-draft`, `telegram-get-drafts`, `telegram-clear-drafts` |\n| **Forum Topics** | `telegram-list-topics`, `telegram-read-topic-messages`, `telegram-create-topic`, `telegram-edit-topic`, `telegram-delete-topic` |\n| **Polls** | `telegram-create-poll` |\n| **Poll Interaction (v1.31.0)** | `telegram-vote-poll`, `telegram-get-poll-results`, `telegram-get-poll-voters`, `telegram-close-poll` |\n| **Reactions** | `telegram-send-reaction`, `telegram-get-reactions`, `telegram-set-default-reaction`, `telegram-get-top-reactions`, `telegram-get-recent-reactions` |\n| **Paid Reactions (v1.31.0)** | `telegram-send-paid-reaction` (★ Stars), `telegram-toggle-paid-reaction-privacy`, `telegram-get-paid-reaction-privacy` |\n| **Audio Transcription (v1.31.0)** | `telegram-transcribe-audio` (Premium), `telegram-get-transcription`, `telegram-rate-transcription` |\n| **Fact-check (v1.31.0)** | `telegram-get-fact-check`, `telegram-edit-fact-check`, `telegram-delete-fact-check` |\n| **Stickers** | `telegram-send-sticker`, `telegram-get-installed-stickers`, `telegram-get-recent-stickers`, `telegram-get-sticker-set`, `telegram-search-sticker-sets` |\n| **Media** | `telegram-send-file`, `telegram-download-media`, `telegram-get-profile-photo`, `telegram-get-web-preview` |\n| **Rich Media Sending** | `telegram-send-voice`, `telegram-send-video-note` (round video), `telegram-send-location` (static or live), `telegram-send-venue`, `telegram-send-contact`, `telegram-send-dice` (🎲🎯🎰🏀⚽🎳), `telegram-send-album` (2–10 grouped photos/videos) |\n| **Groups** | `telegram-create-group`, `telegram-edit-group`, `telegram-invite-to-group`, `telegram-join-chat`, `telegram-leave-group`, `telegram-kick-user`, `telegram-ban-user`, `telegram-unban-user`, `telegram-set-admin`, `telegram-remove-admin`, `telegram-get-my-role`, `telegram-set-chat-permissions`, `telegram-set-slow-mode`, `telegram-get-admin-log` |\n| **Chat Info** | `telegram-get-chat-info`, `telegram-get-chat-members`, `telegram-get-chat-folders` |\n| **Folders (v1.33.0)** | `telegram-create-folder`, `telegram-edit-folder`, `telegram-delete-folder`, `telegram-reorder-folders`, `telegram-get-suggested-folders`, `telegram-toggle-folder-tags` |\n| **Global Privacy (v1.33.0)** | `telegram-get-global-privacy-settings`, `telegram-set-global-privacy-settings` |\n| **Invite Links** | `telegram-create-invite-link`, `telegram-get-invite-links`, `telegram-revoke-invite-link` |\n| **Contacts** | `telegram-get-contacts`, `telegram-add-contact`, `telegram-get-contact-requests` |\n| **Moderation** | `telegram-block-user`, `telegram-unblock-user`, `telegram-report-spam` |\n| **Profiles (read)** | `telegram-get-profile`, `telegram-update-profile` |\n| **Profile (write, v1.32.0)** | `telegram-set-emoji-status` (Premium), `telegram-list-emoji-statuses`, `telegram-clear-recent-emoji-statuses`, `telegram-set-profile-color` (Premium), `telegram-set-birthday`, `telegram-set-personal-channel`, `telegram-set-profile-photo`, `telegram-delete-profile-photo` |\n| **Account** | `telegram-get-sessions`, `telegram-terminate-session`, `telegram-set-privacy`, `telegram-set-auto-delete` |\n| **Pinning** | `telegram-pin-message`, `telegram-unpin-message` |\n| **Chat Settings** | `telegram-mute-chat`, `telegram-archive-chat`, `telegram-pin-chat`, `telegram-mark-dialog-unread` |\n| **Admin Toggles** | `telegram-toggle-channel-signatures`, `telegram-toggle-anti-spam`, `telegram-toggle-forum-mode`, `telegram-toggle-prehistory-hidden`, `telegram-set-chat-reactions`, `telegram-approve-join-request` |\n| **Stats** | `telegram-get-broadcast-stats`, `telegram-get-megagroup-stats` |\n| **Inline Bots & Buttons** | `telegram-inline-query`, `telegram-inline-query-send`, `telegram-press-button`, `telegram-get-message-buttons` |\n| **Real-Time Polling** | `telegram-get-state`, `telegram-get-updates`, `telegram-get-channel-updates` |\n| **Stories (read)** | `telegram-get-all-stories`, `telegram-get-peer-stories`, `telegram-get-stories-by-id`, `telegram-get-story-views` |\n| **Stories (write, v1.30.0)** | `telegram-send-story`, `telegram-edit-story`, `telegram-delete-stories`, `telegram-react-to-story`, `telegram-export-story-link`, `telegram-read-stories`, `telegram-toggle-story-pinned`, `telegram-toggle-story-pinned-to-top`, `telegram-activate-stealth-mode` (Premium), `telegram-get-stories-archive`, `telegram-report-story` |\n| **Discussion (v1.30.0)** | `telegram-get-discussion-message`, `telegram-get-groups-for-discussion` |\n| **Read Receipts (v1.30.0)** | `telegram-get-message-read-participants`, `telegram-get-outbox-read-date` |\n| **Boosts** | `telegram-get-my-boosts`, `telegram-get-boosts-status`, `telegram-get-boosts-list` |\n| **Business (v1.32.0)** | `telegram-get-business-chat-links`, `telegram-create-business-chat-link`, `telegram-edit-business-chat-link`, `telegram-delete-business-chat-link`, `telegram-resolve-business-chat-link`, `telegram-set-business-hours`, `telegram-set-business-location`, `telegram-set-business-greeting`, `telegram-set-business-away`, `telegram-set-business-intro` |\n| **Opt-in (env-gated)** | `telegram-get-group-call`, `telegram-get-group-call-participants` (requires `MCP_TELEGRAM_ENABLE_GROUP_CALLS=1`); Stars & gifts `telegram-get-stars-status`, `telegram-get-stars-transactions`, `telegram-get-stars-topup-options`, `telegram-get-stars-subscriptions`, `telegram-change-stars-subscription`, `telegram-get-available-star-gifts`, `telegram-get-saved-star-gifts`, `telegram-save-star-gift`, `telegram-convert-star-gift` (requires `MCP_TELEGRAM_ENABLE_STARS=1`); `telegram-get-quick-replies`, `telegram-get-quick-reply-messages` (requires `MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1`) |\n\n> **Tip**: Ask your AI assistant *\"What Telegram tools are available?\"* to get the full list with parameters and descriptions.\n\n## Optional Features\n\nSome tools are disabled by default and must be opted in via environment variables:\n\n| Variable | Value | Tools enabled |\n|----------|-------|---------------|\n| `MCP_TELEGRAM_ENABLE_GROUP_CALLS` | `1` | `telegram-get-group-call`, `telegram-get-group-call-participants` |\n| `MCP_TELEGRAM_ENABLE_STARS` | `1` | Stars balance & transactions, top-up options, subscriptions, and Star Gifts (browse / save / convert) |\n| `MCP_TELEGRAM_ENABLE_QUICK_REPLIES` | `1` | `telegram-get-quick-replies`, `telegram-get-quick-reply-messages` |\n\nAdd these to your `.env` file or MCP client config to enable them.\n\n## Development\n\n```bash\nnpm run dev        # Start with file watching (tsx)\nnpm start          # Start the MCP server\nnpm run login      # QR code login in terminal\nnpm run build      # Compile TypeScript\nnpm run lint       # Check code with Biome\nnpm run lint:fix   # Auto-fix lint issues\nnpm run format     # Format code with Biome\n```\n\n## Project Structure\n\n```\nsrc/\n  index.ts            -- MCP server entry point\n  telegram-client.ts  -- TelegramService class (GramJS wrapper)\n  qr-login-cli.ts     -- CLI utility for QR code login\n  tools/              -- Modular tool definitions\n    auth.ts           -- Connection & login\n    messages.ts       -- Send, read, search, edit, delete, forward; inline bots; real-time polling\n    chats.ts          -- Chat listing, group management, admin toggles, stats\n    contacts.ts       -- Contacts, profiles, moderation\n    media.ts          -- Files, photos, downloads\n    reactions.ts      -- Reactions, set-chat-reactions\n    extras.ts         -- Pin, schedule, polls, topics\n    stickers.ts       -- Sticker sets, send, search, browse\n    account.ts        -- Sessions, privacy, auto-delete, profile, emoji status, birthday, chat mute/folders, invite links\n    business.ts       -- Telegram Business: chat links CRUD, work hours, location, greeting/away/intro\n    boosts.ts         -- Boost status, my boosts, boosters list\n    stories.ts        -- Stories: list all, peer, by-id, view stats\n    group-calls.ts    -- Group call info and participants (opt-in: MCP_TELEGRAM_ENABLE_GROUP_CALLS)\n    stars.ts          -- Stars wallet status and transactions (opt-in: MCP_TELEGRAM_ENABLE_STARS)\n    quick-replies.ts  -- Quick replies and messages (opt-in: MCP_TELEGRAM_ENABLE_QUICK_REPLIES)\n    shared.ts         -- Shared utilities\n```\n\n## Tech Stack\n\n- **[TypeScript](https://www.typescriptlang.org/)** -- ES2022, ESM modules\n- **[GramJS](https://github.com/nicedoc/gramjs)** (`telegram`) -- Telegram MTProto client\n- **[@modelcontextprotocol/sdk](https://modelcontextprotocol.io/)** -- MCP server framework\n- **[Zod](https://zod.dev/)** -- Runtime schema validation for tool parameters\n- **[Biome](https://biomejs.dev/)** -- Linter and formatter\n- **[tsx](https://tsx.is/)** -- TypeScript execution without a build step\n- **[dotenv](https://github.com/motdotla/dotenv)** -- Environment variable management\n\n## Troubleshooting\n\n### AUTH_KEY_DUPLICATED\n\nA Telegram session can only be used by **one process at a time**. If you get `AUTH_KEY_DUPLICATED`, it means another process is already using the same session file.\n\n**Solution**: Create separate sessions for each environment:\n\n```bash\n# Local development\nTELEGRAM_SESSION_PATH=~/.mcp-telegram/session-local npx @overpod/mcp-telegram login\n\n# Production server\nTELEGRAM_SESSION_PATH=~/.mcp-telegram/session-prod npx @overpod/mcp-telegram login\n```\n\nThen set `TELEGRAM_SESSION_PATH` in each environment's MCP config accordingly.\n\n## Security\n\n- API credentials are stored in `.env` (gitignored)\n- Session is stored in `~/.mcp-telegram/session` with `0600` permissions (owner-only access)\n- Session directory is created with `0700` permissions\n- Phone number is **not required** -- QR-only authentication\n- No data is sent to third-party services -- all communication goes directly to Telegram servers via MTProto\n- QR login codes are generated locally and never leave your machine\n- **One session per process** -- using the same session in multiple processes simultaneously causes `AUTH_KEY_DUPLICATED` errors (see [Troubleshooting](#troubleshooting))\n- This is a **userbot** (personal account), not a bot -- respect the [Telegram Terms of Service](https://core.telegram.org/api/terms)\n\n## License\n\nMIT\n",
  "bytes": 24817,
  "sha": "0cb8c12060db33b133be712b99a2f8891fa2e79ee7695c321b58cadbf1734630",
  "repo_slug": "mcp-telegram/mcp-telegram",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mcp_telegram_mcp_telegram_ce70f767/readme"
}