{"_id":"mcp-telegram","_rev":"5-3ee08701d2b36eaf9cc5ac1beb4a8bb6","name":"mcp-telegram","dist-tags":{"latest":"3.0.0"},"versions":{"0.0.1":{"name":"mcp-telegram","version":"0.0.1","keywords":["mcp","telegram","cursor","claude","ai","model-context-protocol"],"author":{"name":"Alexey Elizarov","email":"alex.elizarov1@gmail.com"},"license":"MIT","_id":"mcp-telegram@0.0.1","maintainers":[{"name":"beautyfree","email":"alex.elizarov1@gmail.com"}],"homepage":"https://github.com/tacticlaunch/mcp-telegram#readme","bugs":{"url":"https://github.com/tacticlaunch/mcp-telegram/issues"},"bin":{"mcp-telegram":"dist/cli.js","mcp-telegram-server":"dist/cli.js"},"dist":{"shasum":"53d1e56e027954704079e2a763f32eb3c0b3617d","tarball":"https://registry.npmjs.org/mcp-telegram/-/mcp-telegram-0.0.1.tgz","fileCount":28,"integrity":"sha512-tH5fpejWBW6taaRjipMsAomjdpT71DD9g4HvAKuyNrRZ3KyxP2KQ3A+agAJ2N6HK8vTzK9E9hnXlOCJ0To09JA==","signatures":[{"sig":"MEQCIBzVsdKjB8qoaJogA/us4JLUxVGimJPRJx3L6ExRLtrPAiAPNmIN+xpuHxDPuVSW31GRWb84BnXxpv4qoiUo8rh+fA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":55900},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"c524633eec4e37797a255efaa702af091c9d709a","scripts":{"dev":"ts-node src/cli.ts","lint":"eslint src --ext .ts","test":"jest","build":"tsc","start":"node dist/cli.js"},"_npmUser":{"name":"beautyfree","email":"alex.elizarov1@gmail.com"},"repository":{"url":"git+https://github.com/tacticlaunch/mcp-telegram.git","type":"git"},"_npmVersion":"10.2.3","description":"MCP server to work with Telegram through MTProto","directories":{},"_nodeVersion":"20.10.0","dependencies":{"chalk":"^4.1.2","dotenv":"^16.3.1","telegram":"^2.19.10","commander":"^11.1.0","xdg-basedir":"^5.1.0","console-table-printer":"^2.11.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.56.0","ts-jest":"^29.1.1","ts-node":"^10.9.2","typescript":"^5.3.3","@types/node":"^20.10.5","@typescript-eslint/parser":"^6.15.0","@typescript-eslint/eslint-plugin":"^6.15.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-telegram_0.0.1_1743377906710_0.10244330527723333","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"mcp-telegram","version":"0.1.0","keywords":["mcp","telegram","cursor","claude","ai","model-context-protocol"],"author":{"name":"Alexey Elizarov","email":"alex.elizarov1@gmail.com"},"license":"MIT","_id":"mcp-telegram@0.1.0","maintainers":[{"name":"beautyfree","email":"alex.elizarov1@gmail.com"}],"homepage":"https://github.com/tacticlaunch/mcp-telegram#readme","bugs":{"url":"https://github.com/tacticlaunch/mcp-telegram/issues"},"bin":{"mcp-telegram":"dist/index.js"},"dist":{"shasum":"e2b6444c10a4822c9da907810b0ba5266fee708b","tarball":"https://registry.npmjs.org/mcp-telegram/-/mcp-telegram-0.1.0.tgz","fileCount":18,"integrity":"sha512-A7NNODtnUfWNrXTdPMJxYT8+KqCDGtvGq+n4e3RiuTeqtIizLvpz/GuBAw1df5jS5Rqeki7FI6jbrOcwLTsYQA==","signatures":[{"sig":"MEUCIQCPpfGowPC6OvTRSPknVwTTqsMPDhSJJq5ZXUDGV9QUzQIgHW0H/jwalRPm6ssgsGvJBoF99bX1B4BWKUuQJHQj39Q=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":39481},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"0e79494c9f48a55633ecf93b61329e15fba40a78","scripts":{"dev":"ts-node src/index.ts","lint":"eslint src --ext .ts","test":"jest","build":"tsc","start":"node dist/index.js","inspect":"npx fastmcp inspect src/mcp.ts","prepublishOnly":"npm run build && chmod +x dist/index.js"},"_npmUser":{"name":"beautyfree","email":"alex.elizarov1@gmail.com"},"repository":{"url":"git+https://github.com/tacticlaunch/mcp-telegram.git","type":"git"},"_npmVersion":"11.6.2","description":"MCP server to work with Telegram through MTProto","directories":{},"_nodeVersion":"24.13.0","dependencies":{"zod":"^3.24.2","chalk":"^4.1.2","dotenv":"^16.3.1","fastmcp":"^1.20.5","telegram":"^2.19.10","commander":"^11.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.56.0","ts-jest":"^29.1.1","ts-node":"^10.9.2","typescript":"^5.3.3","@types/node":"^20.10.5","@typescript-eslint/parser":"^6.15.0","@typescript-eslint/eslint-plugin":"^6.15.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-telegram_0.1.0_1778976977956_0.20496028852213377","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"mcp-telegram","version":"1.0.0","keywords":["mcp","mcp-server","mcp-telegram","telegram-mcp","model-context-protocol","telegram","telegram-api","telegram-client","telegram-user","telegram-userbot","telegram-search","telegram-messenger","telegram-automation","telegram-integration","mtproto","gramjs","claude","claude-desktop","claude-code","anthropic","cursor","cursor-mcp","vscode-mcp","codex","cline","windsurf","goose","openai","ai","ai-agent","ai-tools","agent","agents","llm","llm-tools","chatbot","automation","stdio","oauth","messaging","chat","channel-management","moderation"],"author":{"name":"Alexey Elizarov","email":"alex.elizarov1@gmail.com"},"license":"MIT","_id":"mcp-telegram@1.0.0","maintainers":[{"name":"beautyfree","email":"alex.elizarov1@gmail.com"}],"homepage":"https://github.com/beautyfree/mcp-telegram#readme","bugs":{"url":"https://github.com/beautyfree/mcp-telegram/issues"},"bin":{"mcp-telegram":"dist/index.js"},"dist":{"shasum":"b1ab0806ffeee2f0b060887c95c2aae6ab62274c","tarball":"https://registry.npmjs.org/mcp-telegram/-/mcp-telegram-1.0.0.tgz","fileCount":41,"integrity":"sha512-Lj9L2WtydrNbrgymdvLNsgzqRe5iienV6x1ptIEtctVD3/A7NtXthPyCA4WYX+Si4cUnaHl2QAIK8Z8j6w7WrA==","signatures":[{"sig":"MEUCIG0P3C/9Ym9r6+JfF9A8o2eq9llVemIjFh8cu7z0bWQLAiEA/TTDPH/1BKmsF2h7a+/n6j75PdrFkEk2BWDSAd8Q5fs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1088550},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"47ffee9f67b45594c1ada094b7b8cf96eb262f18","scripts":{"dev":"tsx watch src/index.ts","lint":"eslint src --ext .ts","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build && chmod +x dist/index.js"},"_npmUser":{"name":"beautyfree","email":"alex.elizarov1@gmail.com"},"repository":{"url":"git+https://github.com/beautyfree/mcp-telegram.git","type":"git"},"_npmVersion":"11.6.2","description":"Telegram MCP server (MTProto). Connect Claude, Cursor, Claude Code, VS Code, Codex, Cline, Windsurf, and other MCP clients to a real Telegram user account: read dialogs, search messages globally, send/edit/forward, react/poll, moderate channels, manage st","directories":{},"_nodeVersion":"24.13.0","dependencies":{"zod":"^3.25.76","open":"^11.0.0","dotenv":"^16.3.1","telegram":"^2.19.10","big-integer":"^1.6.52","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","eslint":"^8.56.0","typescript":"^5.3.3","@types/node":"^20.10.5","@typescript-eslint/parser":"^6.15.0","@typescript-eslint/eslint-plugin":"^6.15.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-telegram_1.0.0_1778999502169_0.27179245033198507","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"mcp-telegram","version":"2.0.0","keywords":["mcp","mcp-server","mcp-telegram","telegram-mcp","model-context-protocol","telegram","telegram-api","telegram-client","telegram-user","telegram-userbot","telegram-search","telegram-messenger","telegram-automation","telegram-integration","mtproto","gramjs","claude","claude-desktop","claude-code","anthropic","cursor","cursor-mcp","vscode-mcp","codex","cline","windsurf","goose","openai","ai","ai-agent","ai-tools","agent","agents","llm","llm-tools","chatbot","automation","stdio","oauth","messaging","chat","channel-management","moderation"],"author":{"name":"Alexey Elizarov","email":"alex.elizarov1@gmail.com"},"license":"MIT","_id":"mcp-telegram@2.0.0","maintainers":[{"name":"beautyfree","email":"alex.elizarov1@gmail.com"}],"homepage":"https://github.com/beautyfree/mcp-telegram#readme","bugs":{"url":"https://github.com/beautyfree/mcp-telegram/issues"},"bin":{"mcp-telegram":"dist/index.js"},"dist":{"shasum":"442e194feaa6b2dfa3d7393bd5921c72dc92d127","tarball":"https://registry.npmjs.org/mcp-telegram/-/mcp-telegram-2.0.0.tgz","fileCount":41,"integrity":"sha512-tINuKyVLo2Svd2kOzrHF5z1FdU1tXoTXZKoN8lHX5xVLzvGrhD/w+IJ8oOtP81pmKEwzRRBeVNRcUDccNT1sZw==","signatures":[{"sig":"MEUCIQCYL7oeLdhAxDGCn2IBQwr4hsgDP1oiZQSJtLsOgxkgYQIgEG5wPDxMLbHZ/9mGnQ+rbPi+zVpUwaCf810wIemCCRM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1088978},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"5186a5b97d7842a0b859f1f4db4a13bc4e2e30d4","scripts":{"dev":"tsx watch src/index.ts","lint":"eslint src --ext .ts","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build && chmod +x dist/index.js"},"_npmUser":{"name":"beautyfree","email":"alex.elizarov1@gmail.com"},"repository":{"url":"git+https://github.com/beautyfree/mcp-telegram.git","type":"git"},"_npmVersion":"11.6.2","description":"Telegram MCP server (MTProto). Connect Claude, Cursor, Claude Code, VS Code, Codex, Cline, Windsurf, and other MCP clients to a real Telegram user account: read dialogs, search messages globally, send/edit/forward, react/poll, moderate channels, manage st","directories":{},"_nodeVersion":"24.13.0","dependencies":{"zod":"^3.25.76","open":"^11.0.0","dotenv":"^16.3.1","telegram":"^2.19.10","big-integer":"^1.6.52","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","eslint":"^8.56.0","typescript":"^5.3.3","@types/node":"^20.10.5","@typescript-eslint/parser":"^6.15.0","@typescript-eslint/eslint-plugin":"^6.15.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-telegram_2.0.0_1778999829935_0.7346239114658526","host":"s3://npm-registry-packages-npm-production"}},"3.0.0":{"name":"mcp-telegram","version":"3.0.0","description":"Telegram MCP server (MTProto). Connect Claude, Codex, Cursor, Claude Code, VS Code, Cline, Windsurf, and other MCP clients to a real Telegram user account: read dialogs, search messages globally, send/edit/forward, react/poll, moderate channels, tag Saved","type":"module","main":"dist/index.js","types":"dist/index.d.ts","author":{"name":"Alexey Elizarov","email":"alex.elizarov1@gmail.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/beautyfree/mcp-telegram.git"},"homepage":"https://github.com/beautyfree/mcp-telegram#readme","bugs":{"url":"https://github.com/beautyfree/mcp-telegram/issues"},"keywords":["mcp","mcp-server","mcp-telegram","telegram-mcp","model-context-protocol","telegram","telegram-api","telegram-client","telegram-user","telegram-userbot","telegram-search","telegram-messenger","telegram-automation","telegram-integration","mtproto","gramjs","claude","claude-desktop","claude-code","anthropic","cursor","cursor-mcp","vscode-mcp","codex","cline","windsurf","goose","openai","ai","ai-agent","ai-tools","agent","agents","llm","llm-tools","chatbot","automation","stdio","oauth","messaging","chat","channel-management","moderation","agent-skills","skill","skills","claude-code-skills","codex-skills","cursor-rules","saved-messages","telegram-tags"],"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsx watch src/index.ts","lint":"eslint src --ext .ts","prepublishOnly":"npm run build && chmod +x dist/index.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","big-integer":"^1.6.52","dotenv":"^16.3.1","open":"^11.0.0","telegram":"^2.19.10","zod":"^3.25.76"},"devDependencies":{"@types/node":"^20.10.5","@typescript-eslint/eslint-plugin":"^6.15.0","@typescript-eslint/parser":"^6.15.0","eslint":"^8.56.0","tsx":"^4.19.2","typescript":"^5.3.3"},"engines":{"node":">=20.0.0"},"bin":{"mcp-telegram":"dist/index.js"},"publishConfig":{"access":"public"},"gitHead":"f61b257a89b21a1f42a98bbefcbf7a24a83a53d8","_id":"mcp-telegram@3.0.0","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-cYfNjPoiydZ5PMhYjTdAXfxv0r5wt0nrONv9UKJJSeJveRSJK05fOOsrJJfahNylB7ap45Bjkowq8lRD9l55ug==","shasum":"2c913855015b6127b37dc38247593610c99db137","tarball":"https://registry.npmjs.org/mcp-telegram/-/mcp-telegram-3.0.0.tgz","fileCount":38,"unpackedSize":964538,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD+c9XoP+/qFppD4Q+63po1ZiUhdUleeuF6c4HBjXq+YAIgRQ+gFXVtXzCFv5uxbFTGS/O0aw4rcgkz//ykw8FWVb8="}]},"_npmUser":{"name":"beautyfree","email":"alex.elizarov1@gmail.com"},"directories":{},"maintainers":[{"name":"beautyfree","email":"alex.elizarov1@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-telegram_3.0.0_1779102950762_0.3819374603299843"},"_hasShrinkwrap":false}},"time":{"created":"2025-03-30T23:38:26.640Z","modified":"2026-05-18T11:15:51.066Z","0.0.1":"2025-03-30T23:38:26.924Z","0.1.0":"2026-05-17T00:16:18.084Z","1.0.0":"2026-05-17T06:31:42.376Z","2.0.0":"2026-05-17T06:37:10.128Z","3.0.0":"2026-05-18T11:15:50.964Z"},"bugs":{"url":"https://github.com/beautyfree/mcp-telegram/issues"},"author":{"name":"Alexey Elizarov","email":"alex.elizarov1@gmail.com"},"license":"MIT","homepage":"https://github.com/beautyfree/mcp-telegram#readme","keywords":["mcp","mcp-server","mcp-telegram","telegram-mcp","model-context-protocol","telegram","telegram-api","telegram-client","telegram-user","telegram-userbot","telegram-search","telegram-messenger","telegram-automation","telegram-integration","mtproto","gramjs","claude","claude-desktop","claude-code","anthropic","cursor","cursor-mcp","vscode-mcp","codex","cline","windsurf","goose","openai","ai","ai-agent","ai-tools","agent","agents","llm","llm-tools","chatbot","automation","stdio","oauth","messaging","chat","channel-management","moderation","agent-skills","skill","skills","claude-code-skills","codex-skills","cursor-rules","saved-messages","telegram-tags"],"repository":{"type":"git","url":"git+https://github.com/beautyfree/mcp-telegram.git"},"description":"Telegram MCP server (MTProto). Connect Claude, Codex, Cursor, Claude Code, VS Code, Cline, Windsurf, and other MCP clients to a real Telegram user account: read dialogs, search messages globally, send/edit/forward, react/poll, moderate channels, tag Saved","maintainers":[{"name":"beautyfree","email":"alex.elizarov1@gmail.com"}],"readme":"<p align=\"center\">\n  <img width=\"20%\" src=\"assets/logo.png\" alt=\"mcp-telegram\" />\n</p>\n<p align=\"center\">\n  <h1 align=\"center\">mcp-telegram</h1>\n</p>\n<p align=\"center\">\n  <b>Telegram MCP server</b> for Claude, Codex, Cursor, Claude Code, VS Code, Cline, Windsurf, and other MCP clients. Real Telegram user account via MTProto, browser-based local sign-in, 100+ tools. Need lazy-loading + lower context cost? See <a href=\"https://github.com/beautyfree/telegram-agent\"><b>telegram-agent</b></a>, the skill-based companion.\n</p>\n<div align=\"center\">\n\n[![npm version](https://badgen.net/npm/v/mcp-telegram)](https://www.npmjs.com/package/mcp-telegram)\n[![License](https://img.shields.io/npm/l/mcp-telegram)](https://github.com/beautyfree/mcp-telegram/blob/main/LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](package.json)\n\n</div>\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that connects [Claude Desktop](https://claude.ai), [Codex CLI](https://github.com/openai/codex), [Cursor](https://cursor.com), [Claude Code](https://claude.ai/code), VS Code, Cline, Windsurf, Goose, and any other MCP-compatible client to a real Telegram user account via [MTProto](https://core.telegram.org/mtproto)—so your agent can read, search, send, moderate, and manage Telegram chats from chat or automated tool calls instead of clicking through the Telegram UI.\n\n**Use it to:** read dialogs and search messages globally · send/edit/forward/react/poll · download media and transcribe voice notes · moderate channels (ban/restrict/promote, invite links, slow-mode, admin log, forum topics) · manage stories, contacts, drafts, notifications, folders, privacy · or fall through to the raw MTProto bridge for anything else. All against a single signed-in user account—no bot required.\n\n> [!WARNING]\n> This server signs in as a real Telegram user (not a bot). Sessions live in `~/.telegram-agent/`. Treat that directory like a password.\n\n## Prerequisites\n\n1. Node.js `>=20`\n2. Telegram API credentials from [my.telegram.org/apps](https://my.telegram.org/apps) — `api_id` and `api_hash`\n\n## Want a lighter transport?\n\nThis package is the **MCP server** — every tool schema (~12,700 tokens) sits in your agent's context on every turn. Good for any MCP client and for hosted runtimes that can't shell out.\n\nIf your agent is **Claude Code / Codex CLI / Cursor / Gemini CLI / Cline / Windsurf**, there's a [companion package — `telegram-agent`](https://github.com/beautyfree/telegram-agent) — that ships the same Telegram surface as a [universal agent skill](https://code.claude.com/docs/en/skills). The agent only loads the skill instructions when your prompt mentions Telegram — **~50× lower context cost** in idle. Standalone (no MCP server in the loop), but uses the same `~/.telegram-agent/` session store as this package — sign in once, use either or both.\n\n```bash\nnpm i -g telegram-agent\ntelegram-agent login\nnpx skills add beautyfree/telegram-agent -a claude-code -g\n```\n\nContinue below for the MCP install path.\n\n## Install\n\n**Option A — automatic, all clients:**\n\n```bash\nnpx add-mcp mcp-telegram \\\n  --env TELEGRAM_API_ID=123456 \\\n  --env TELEGRAM_API_HASH=abc...\n```\n\n`add-mcp` (from Neon) writes the correct config for Claude Desktop, Claude Code, Cursor, VS Code, Codex, Gemini CLI, Cline, Zed, Goose, OpenCode, and others. Pick the client in the interactive prompt.\n\n> [!IMPORTANT]\n> Both env vars are required. Get them from [my.telegram.org/apps](https://my.telegram.org/apps).\n\n**Option B — manual config:**\n\n<details>\n<summary><b>Claude Desktop</b> (<code>claude_desktop_config.json</code>)</summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"telegram\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-telegram\"],\n      \"env\": {\n        \"TELEGRAM_API_ID\": \"123456\",\n        \"TELEGRAM_API_HASH\": \"abc...\"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><b>Cursor</b> (<code>~/.cursor/mcp.json</code>)</summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"telegram\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-telegram\"],\n      \"env\": {\n        \"TELEGRAM_API_ID\": \"123456\",\n        \"TELEGRAM_API_HASH\": \"abc...\"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><b>VS Code</b> (<code>.vscode/mcp.json</code>)</summary>\n\n```json\n{\n  \"servers\": {\n    \"telegram\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-telegram\"],\n      \"env\": {\n        \"TELEGRAM_API_ID\": \"123456\",\n        \"TELEGRAM_API_HASH\": \"abc...\"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><b>Claude Code</b></summary>\n\n```bash\nclaude mcp add telegram \\\n  -e TELEGRAM_API_ID=123456 \\\n  -e TELEGRAM_API_HASH=abc... \\\n  -- npx -y mcp-telegram\n```\n</details>\n\n<details>\n<summary><b>Codex CLI</b> (<code>~/.codex/config.toml</code>) — <a href=\"https://github.com/openai/codex\">install</a></summary>\n\n```toml\n[mcp_servers.telegram]\ncommand = \"npx\"\nargs = [\"-y\", \"mcp-telegram\"]\nenv = { TELEGRAM_API_ID = \"123456\", TELEGRAM_API_HASH = \"abc...\" }\n```\n</details>\n\n## First-time sign in\n\nAsk your agent:\n\n> Sign in to my Telegram.\n\nThe agent calls the `login` tool. A browser tab opens. Enter your phone number, the SMS code, and 2FA password if you have one. The tab shows a green checkmark — you can close it. The session is now stored locally and the agent can read your Telegram.\n\nTo add another account, ask the agent to call `login` again.\n\n## Tools\n\n102 tools covering the full Telegram user-account surface. Common ones below; the rest are grouped under collapsibles. Every tool accepts an optional `accountId` (omit when only one account is signed in). `peer` accepts a numeric chat id, an `@username`, or the literal `\"me\"` (Saved Messages).\n\n**Top of the menu:**\n\n| Tool | What it does |\n| --- | --- |\n| `login` | Open the browser-based sign-in flow. Adds an account. |\n| `list_accounts` | List signed-in accounts. |\n| `list_dialogs` | List dialogs/chats/channels. Filters: `unread`, `archived`, `ignorePinned`, `folder`, `limit`. |\n| `list_messages` | List messages in a dialog. Newest first. |\n| `search_messages` | Search inside one dialog: `query`, `filter` (photos/videos/url/voice/...), `fromUser`, date range. |\n| `search_global` | Search across every chat you have. |\n| `search_dialogs` | Find dialogs by name/title/username substring. |\n| `send_message` | Send text. Supports `replyTo`, `topMsgId`, `parseMode`, `schedule`, `silent`. |\n| `send_file` | Send a file (local path or `https://` URL). Pass an array for an album. |\n| `download_media` | Save the media on a message to disk. |\n| `transcribe_message` | Transcribe a voice/video note (Premium). |\n| `invoke_mtproto` | Call any raw MTProto method by name. Auto-resolves `peer`/`channel`/`user` strings. |\n\n<details>\n<summary><b>Sessions (local)</b> (4)</summary>\n\nThese are local-only: they manage which Telegram sessions live in `~/.telegram-agent/` and the settings UI. No Telegram API call beyond the sign-in flow itself.\n\n| Tool | What it does |\n| --- | --- |\n| `list_accounts` | List signed-in accounts. |\n| `login` | Browser-based sign-in. Adds an account. |\n| `logout` | Drop a local session and revoke it on Telegram. |\n| `open_settings` | Open the local settings page (tool surface + read-only). |\n\n</details>\n\n<details>\n<summary><b>Profile</b> (5)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `get_me` | Return the profile of the authenticated user. |\n| `update_profile` | Change own first/last name and bio. |\n| `update_my_username` | Set or clear own `@username`. |\n| `set_birthday` | Set the account birthday. |\n| `set_profile_photo` | Upload a new avatar (local path or URL). |\n\n</details>\n\n<details>\n<summary><b>Dialog discovery</b> (5)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `list_dialogs` | List dialogs. Filters: `unread`, `archived`, `ignorePinned`, `folder`, `limit`. |\n| `search_dialogs` | Find dialogs by name/title/username substring. |\n| `resolve_username` | Resolve `@username` to a user/channel/chat entity. |\n| `list_folders` | List custom dialog folders (chat filters). |\n| `list_contacts` | List contacts. |\n\n</details>\n\n<details>\n<summary><b>Messages — read & search</b> (6)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `list_messages` | List messages in a dialog. |\n| `search_messages` | Search inside one dialog (text, type filter, sender, date range). |\n| `search_global` | Search across every chat. |\n| `get_message` | Fetch one or more messages by id. |\n| `get_message_reactions` | Get reactions on messages. |\n| `mark_as_read` | Mark messages read up to an id. |\n\n</details>\n\n<details>\n<summary><b>Messages — write</b> (8)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `send_message` | Send text. |\n| `edit_message` | Edit a previously sent message. |\n| `delete_messages` | Delete by id (optionally revoke for all). |\n| `forward_messages` | Forward messages between dialogs. |\n| `pin_message` / `unpin_message` | Pin / unpin in a dialog. |\n| `send_reaction` | Set reactions on a message. |\n| `send_message_to_phone` | Send to a phone number, auto-creates a temporary contact. |\n\n</details>\n\n<details>\n<summary><b>Media</b> (4)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `send_file` | Send a file (path or URL). Albums via array. |\n| `download_media` | Save a message's media to disk. |\n| `download_profile_photo` | Save a peer's avatar to disk. |\n| `transcribe_message` | Transcribe voice/video (Premium). |\n\n</details>\n\n<details>\n<summary><b>Polls</b> (4)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `send_poll` | Send a poll. Supports quiz, multiple-choice, anonymous, close period. |\n| `vote_poll` | Cast a vote. |\n| `close_poll` | Finalize a poll. |\n| `get_poll_results` | Fetch tally. |\n\n</details>\n\n<details>\n<summary><b>Reactions</b> (3)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `send_reaction` | Set emoji reactions on a message. |\n| `get_message_reactions` | Read reactions. |\n| `set_default_reaction` | Set account-wide default. |\n\n</details>\n\n<details>\n<summary><b>Stories</b> (6)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `list_stories` | Feed of contacts' stories. |\n| `get_peer_stories` | One peer's stories. |\n| `send_story` | Post a story (photo or video). |\n| `delete_story` | Delete own stories. |\n| `view_story` | Mark stories viewed. |\n| `get_story_viewers` | List who viewed your story. |\n\n</details>\n\n<details>\n<summary><b>Channel / group moderation</b> (11)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `ban_user` | Full ban (optional `untilDate`). |\n| `unban_user` | Lift restrictions. |\n| `restrict_user` | Apply a custom rights mask. |\n| `promote_admin` | Grant admin rights (with rank). |\n| `demote_admin` | Strip admin rights. |\n| `invite_user` | Add users to a channel/supergroup. |\n| `kick_participant` | Kick from chat/channel. |\n| `get_participant` | Single participant info. |\n| `list_participants` | Members with filter (admins/banned/bots/...) and substring search. |\n| `delete_user_history` | Remove every message by a user. |\n| `get_admin_log` | Recent admin events with event-type filter. |\n\n</details>\n\n<details>\n<summary><b>Channel / group settings</b> (12)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `edit_title` | Change title (works for channels, supergroups, and basic groups). |\n| `edit_about` | Change description. |\n| `edit_photo` | Change avatar (path or URL). |\n| `update_username` | Set/clear public `@username`. |\n| `check_username` | Check availability. |\n| `set_slow_mode` | Set slow-mode seconds. |\n| `toggle_signatures` | Author signatures on channel posts. |\n| `toggle_pre_history_hidden` | Hide history from new members. |\n| `toggle_join_request` | Require admin approval to join. |\n| `leave_channel` | Leave a channel/supergroup. |\n| `get_channel_info` | Extended info (about, counts, linked chat, slow-mode). |\n| `get_user_info` | Extended user info (bio, common chats). |\n\n</details>\n\n<details>\n<summary><b>Channel / group lifecycle</b> (4)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `create_channel` | New broadcast channel or supergroup (optional forum mode). |\n| `delete_channel` | Permanently delete. |\n| `migrate_chat` | Basic group → supergroup. |\n| `transfer_ownership` | Hand over creator rights (requires 2FA password). |\n\n</details>\n\n<details>\n<summary><b>Invite links</b> (4)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `create_invite_link` | New link with optional expiry, usage cap, join-request gate. |\n| `list_invite_links` | List active or revoked links. |\n| `revoke_invite_link` | Revoke a specific link. |\n| `list_invite_joiners` | List users that joined via a link. |\n\n</details>\n\n<details>\n<summary><b>Forum topics</b> (3)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `list_topics` | List forum topics. |\n| `create_topic` | Create a new topic. |\n| `edit_topic` | Rename, re-icon, close, hide. |\n\n</details>\n\n<details>\n<summary><b>Drafts</b> (3)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `save_draft` | Save a draft for a dialog. |\n| `clear_draft` | Drop the draft for a dialog. |\n| `list_drafts` | List all dialog drafts. |\n\n</details>\n\n<details>\n<summary><b>Notifications</b> (4)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `mute_peer` | Mute a chat (optional `untilDate`). |\n| `unmute_peer` | Unmute. |\n| `get_notify_settings` | Read settings. |\n| `set_notify_settings` | Update mute, previews, sound, story-mute. |\n\n</details>\n\n<details>\n<summary><b>Folders (chat filters)</b> (4)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `create_folder` | New folder with include/exclude rules. |\n| `edit_folder` | Replace folder rules. |\n| `delete_folder` | Remove a folder. |\n| `reorder_folders` | Set display order. |\n\n</details>\n\n<details>\n<summary><b>Contacts</b> (4)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `list_contacts` | All contacts. |\n| `add_contact` | Add a user to contacts. |\n| `delete_contact` | Remove users from contacts. |\n| `search_contacts` | Search contacts + global directory. |\n\n</details>\n\n<details>\n<summary><b>Privacy & blocking</b> (5)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `block_user` / `unblock_user` | Block / unblock. |\n| `list_blocked` | Block list. |\n| `get_privacy` | Read a privacy key. |\n| `set_privacy` | Update a privacy key (mode + allow/disallow lists). |\n\n</details>\n\n<details>\n<summary><b>Stickers</b> (3)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `get_my_stickers` | Installed sticker sets. |\n| `install_sticker_set` | Install by short name. |\n| `add_recent_sticker` | Pin a sticker to recent. |\n\n</details>\n\n<details>\n<summary><b>Premium boosts</b> (2)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `get_my_boosts` | List your boost slots. |\n| `apply_boost` | Apply slots to a channel. |\n\n</details>\n\n<details>\n<summary><b>Bots & raw MTProto</b> (2)</summary>\n\n| Tool | What it does |\n| --- | --- |\n| `get_inline_bot_results` | Run an inline bot query. |\n| `invoke_mtproto` | Call any MTProto method by qualified name (e.g. `messages.SendMessage`, `stories.GetAllStories`). String values for `peer`/`channel`/`user`/`fromPeer`/`toPeer`/`bot`/`chat` are auto-resolved to InputPeer / InputUser. |\n\n</details>\n\n### Gating which tools are exposed\n\nThree env vars, applied in order:\n\n| Variable | Effect |\n| --- | --- |\n| `MCP_TELEGRAM_READONLY=1` | Hide every destructive / mutating tool. |\n| `MCP_TELEGRAM_TOOLS=name1,name2,prefix*` | Strict allowlist — only these tools register. |\n| `MCP_TELEGRAM_DISABLE=name1,prefix*` | Blocklist applied after the allowlist. |\n\nExamples:\n\n```bash\nMCP_TELEGRAM_READONLY=1                                    # read-only agent\nMCP_TELEGRAM_TOOLS='login,list*,search*,get*'              # discovery-only\nMCP_TELEGRAM_DISABLE='delete*,ban*,kick*,create_channel,delete_channel,transfer_ownership,invokeMtproto'  # safer write set\n```\n\n## Environment\n\n| Variable | Required | Default | Notes |\n| --- | --- | --- | --- |\n| `TELEGRAM_API_ID` | yes | — | From my.telegram.org/apps. If unset, the auth page prompts for it and saves to `state.json`. |\n| `TELEGRAM_API_HASH` | yes | — | Same as above. |\n| `TELEGRAM_AGENT_HOME` | no | `~/.telegram-agent` | State + per-account session storage. Legacy `MCP_TELEGRAM_HOME` still accepted. If only `~/.mcp-telegram` exists from a previous install, it's used automatically. |\n| `TELEGRAM_AGENT_DOWNLOADS` | no | `$TELEGRAM_AGENT_HOME/downloads` | Where `download_media` / `download_profile_photo` save files. Legacy `MCP_TELEGRAM_DOWNLOADS` still accepted. |\n| `MCP_TELEGRAM_READONLY` | no | — | Set to `1`/`true`/`yes` to hide every destructive tool. |\n| `MCP_TELEGRAM_TOOLS` | no | — | Strict allowlist. Comma-separated tool names; supports `prefix*` wildcards. If set, anything not matched is hidden. |\n| `MCP_TELEGRAM_DISABLE` | no | — | Blocklist applied after the allowlist. Same syntax. |\n| `LOG_LEVEL` | no | `info` | `debug` for verbose stderr. |\n\n### Choosing which tools the agent sees\n\nThe three gating vars stack — `MCP_TELEGRAM_READONLY` → `MCP_TELEGRAM_TOOLS` → `MCP_TELEGRAM_DISABLE`.\n\n```bash\n# Read-only agent — every mutating tool is hidden\nMCP_TELEGRAM_READONLY=1\n\n# Discovery-only — only login + the list/search/get tools\nMCP_TELEGRAM_TOOLS='login,list*,search*,get*,resolveUsername'\n\n# Allow writes but keep destructive ones away from the agent\nMCP_TELEGRAM_DISABLE='delete*,ban*,kick*,create_channel,delete_channel,transfer_ownership,invokeMtproto'\n\n# Specific surface: read + send/edit only\nMCP_TELEGRAM_TOOLS='login,list_accounts,list_dialogs,list_messages,search_messages,search_global,send_message,editMessage'\n```\n\nIn an MCP client config, drop these into the same `env` block as `TELEGRAM_API_ID`/`TELEGRAM_API_HASH`. To verify, re-open your client — the tools the server advertises are exactly the ones registered after the gates run.\n\n## Data layout\n\n```\n~/.telegram-agent/\n├── state.json          known accounts (no secrets in here)\n└── sessions/\n    └── <account_id>/   per-account MTProto session\n```\n\nIf a Telegram session is invalidated server-side (logged out from another device, password rotated, etc.), the next tool call returns an error telling the agent to call `login` to re-authorize.\n\n## Development\n\n```bash\ngit clone https://github.com/beautyfree/mcp-telegram\ncd mcp-telegram\nnpm install\necho \"TELEGRAM_API_ID=...\\nTELEGRAM_API_HASH=...\" > .env\nnpm run dev\n```\n\nLayout:\n\n```\nsrc/\n├── index.ts           bin entry — stdio MCP server, tool registrations\n├── telegram.ts        MTProto client + login state machine\n├── auth-browser.ts    ephemeral HTTP server that drives the browser flow\n├── auth-page.ts       inline HTML for the auth page\n├── state.ts           persistent state in ~/.telegram-agent/\n└── logger.ts\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n<details>\n<summary>Also known as</summary>\n\nTelegram MCP · MCP Telegram · Telegram MCP server · Telegram for Claude · Telegram for Cursor · Telegram for Claude Code · Telegram for VS Code · Telegram for Codex · Telegram for Cline · Telegram for Windsurf · Telegram for AI agents · Telegram MTProto MCP · Telegram user-account MCP · Telegram automation MCP · Model Context Protocol Telegram · MCP server Telegram · gramjs MCP\n\n</details>\n","readmeFilename":"README.md"}