{"_id":"@thenavidm/telegram-mcp-cli","_rev":"9-ab8b0f933f23e033297b6f25306cebc3","name":"@thenavidm/telegram-mcp-cli","dist-tags":{"latest":"0.5.0"},"versions":{"0.1.0":{"name":"@thenavidm/telegram-mcp-cli","version":"0.1.0","keywords":["mcp","model-context-protocol","telegram","mtproto","cli","claude","ai-agents"],"author":{"url":"https://navid.me","name":"Navid Moazzez"},"license":"MIT","_id":"@thenavidm/telegram-mcp-cli@0.1.0","maintainers":[{"name":"thenavidm","email":"n@navid.me"}],"homepage":"https://github.com/thenavidm/telegram-mcp-cli#readme","bugs":{"url":"https://github.com/thenavidm/telegram-mcp-cli/issues"},"bin":{"telegram-cli":"dist/index.js","telegram-mcp":"dist/index.js"},"dist":{"shasum":"713220db9cc1233c13fb2b53bddae18b02ff9c63","tarball":"https://registry.npmjs.org/@thenavidm/telegram-mcp-cli/-/telegram-mcp-cli-0.1.0.tgz","fileCount":52,"integrity":"sha512-z/ApEH6+6tko6dRaQIapwwJgkVkK8fT2B0otq/65qjL+1Xny+u9GWw6n8uZVo63R8Ysq5V2/p6xVcClli3sXUg==","signatures":[{"sig":"MEYCIQDfJZ07d6LdcEVuekyP2QksMHMimd5BKuQMzzASIDWusAIhAKfCcJLQA4ww6Mlw/iyNkR2q/AgyH6uhFhWkv4vRAdEY","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":178860},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"1cea989ebd5ff778d4954e5cf7647d8154affec9","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"thenavidm","email":"n@navid.me"},"repository":{"url":"git+https://github.com/thenavidm/telegram-mcp-cli.git","type":"git"},"_npmVersion":"10.9.8","description":"Telegram MCP server and CLI for Claude Code and AI agents. Full account access over MTProto: chats, history, search, sending, media and contacts.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"zod":"^3.23.8","telegram":"^2.26.22","zod-to-json-schema":"^3.24.1","@modelcontextprotocol/sdk":"^1.18.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.0","typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/telegram-mcp-cli_0.1.0_1788807211601_0.9873165702431628","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@thenavidm/telegram-mcp-cli","version":"0.2.0","keywords":["mcp","model-context-protocol","telegram","mtproto","cli","claude","ai-agents"],"author":{"url":"https://navid.me","name":"Navid Moazzez"},"license":"MIT","_id":"@thenavidm/telegram-mcp-cli@0.2.0","maintainers":[{"name":"thenavidm","email":"n@navid.me"}],"homepage":"https://github.com/thenavidm/telegram-mcp-cli#readme","bugs":{"url":"https://github.com/thenavidm/telegram-mcp-cli/issues"},"bin":{"telegram-cli":"dist/index.js","telegram-mcp":"dist/index.js"},"dist":{"shasum":"1b1c6b61c765ed41bdc674eb2fbdbb9f3d42ea3d","tarball":"https://registry.npmjs.org/@thenavidm/telegram-mcp-cli/-/telegram-mcp-cli-0.2.0.tgz","fileCount":67,"integrity":"sha512-JvYpQ/Yj5RGkDpTLd+eAb/nqhWpGlJj6nUdxo6+xGwolsuicAPNt049DvQ1bKvTvIZl1XHHvxu0z9KwRSBiGxQ==","signatures":[{"sig":"MEQCICbW76pXj13io2O2R4QoPrsj5cbxkO6VF/k73KCfNRXHAiBQ+55qHWCCp2FoO2YlV1FqY9TTOTR5hPruiPKdNHZsPw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":285922},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"be4d50ea3364284bf7d6015f03510a10e3015802","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"thenavidm","email":"n@navid.me"},"repository":{"url":"git+https://github.com/thenavidm/telegram-mcp-cli.git","type":"git"},"_npmVersion":"10.9.8","description":"Telegram MCP server and CLI for Claude Code and AI agents. 54 tools for chats, history, search, sending, media, contacts, groups, admin, reactions, polls and folders, on your real Telegram account over MTProto.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"zod":"^3.23.8","telegram":"^2.26.22","zod-to-json-schema":"^3.24.1","@modelcontextprotocol/sdk":"^1.18.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.0","typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/telegram-mcp-cli_0.2.0_1788809669473_0.7640080029471263","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@thenavidm/telegram-mcp-cli","version":"0.3.0","keywords":["mcp","model-context-protocol","telegram","mtproto","cli","claude","ai-agents"],"author":{"url":"https://navid.me","name":"Navid Moazzez"},"license":"MIT","_id":"@thenavidm/telegram-mcp-cli@0.3.0","maintainers":[{"name":"thenavidm","email":"n@navid.me"}],"homepage":"https://github.com/thenavidm/telegram-mcp-cli#readme","bugs":{"url":"https://github.com/thenavidm/telegram-mcp-cli/issues"},"bin":{"telegram-cli":"dist/index.js","telegram-mcp":"dist/index.js"},"dist":{"shasum":"4d105b8909bdc97a1a9c9593483fbeff68ab59e9","tarball":"https://registry.npmjs.org/@thenavidm/telegram-mcp-cli/-/telegram-mcp-cli-0.3.0.tgz","fileCount":79,"integrity":"sha512-mTZ098PFJFMtNPgP3uV2W1/jg7A9mCpZ/wxXS8oyVBhHBK6aRvZkvlIKB97DW9nXaR+pUVke8pkqkMGlBPmClA==","signatures":[{"sig":"MEUCIQCUKPBcs7UPCYFq6ZvQa4jNHFjwMOjNLYOfFatuEs4kugIgVqjIpUJD6FFG/o9hwGA2nmgfgQId9idxk9hV2oqXCno=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":355303},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"f30d3415e4150f6037e5c55578ef8add3483697f","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"thenavidm","email":"n@navid.me"},"repository":{"url":"git+https://github.com/thenavidm/telegram-mcp-cli.git","type":"git"},"_npmVersion":"10.9.8","description":"Telegram MCP server and CLI for Claude Code and AI agents. 74 tools for chats, history, search, sending, media, contacts, groups, admin, topics, reactions, polls, folders and privacy, on your real Telegram account over MTProto.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"zod":"^3.23.8","telegram":"^2.26.22","zod-to-json-schema":"^3.24.1","@modelcontextprotocol/sdk":"^1.18.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.0","typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/telegram-mcp-cli_0.3.0_1788810336389_0.5288077800049984","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@thenavidm/telegram-mcp-cli","version":"0.4.0","keywords":["mcp","model-context-protocol","telegram","mtproto","cli","claude","ai-agents"],"author":{"url":"https://navid.me","name":"Navid Moazzez"},"license":"MIT","_id":"@thenavidm/telegram-mcp-cli@0.4.0","maintainers":[{"name":"thenavidm","email":"n@navid.me"}],"homepage":"https://github.com/thenavidm/telegram-mcp-cli#readme","bugs":{"url":"https://github.com/thenavidm/telegram-mcp-cli/issues"},"bin":{"telegram-cli":"dist/index.js","telegram-mcp":"dist/index.js"},"dist":{"shasum":"2b926b7bdb4d4fee89476530d8bc4ab8e667a73f","tarball":"https://registry.npmjs.org/@thenavidm/telegram-mcp-cli/-/telegram-mcp-cli-0.4.0.tgz","fileCount":82,"integrity":"sha512-mAWbGXk9QxBPjMnzJsTkveuIMu/R6tRQSvh0FXO5rqB8pJNZCcvmCbzLXD8zw+yycz13MGkdNtjP6bmDe7vuog==","signatures":[{"sig":"MEUCIQCkhcYrgIyhqhl9hlN9RlT04jWKpMH4WcAxRjRhPQY3RAIgTFsT/rx7bduEBa4mFpEvmISwNeW25ENiRBeySidQNJs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":374152},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"2f22482c80e78b1192e59b5bcfdb7100804f44cc","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"thenavidm","email":"n@navid.me"},"repository":{"url":"git+https://github.com/thenavidm/telegram-mcp-cli.git","type":"git"},"_npmVersion":"10.9.8","description":"Telegram MCP server and CLI for Claude Code and AI agents. 74 tools for chats, history, search, sending, media, contacts, groups, admin, topics, reactions, polls, folders and privacy, on your real Telegram account over MTProto.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"zod":"^3.23.8","telegram":"^2.26.22","zod-to-json-schema":"^3.24.1","@modelcontextprotocol/sdk":"^1.18.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.0","typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/telegram-mcp-cli_0.4.0_1788811247241_0.3630364271959159","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@thenavidm/telegram-mcp-cli","version":"0.4.1","keywords":["mcp","model-context-protocol","telegram","mtproto","cli","claude","ai-agents"],"author":{"url":"https://navid.me","name":"Navid Moazzez"},"license":"MIT","_id":"@thenavidm/telegram-mcp-cli@0.4.1","maintainers":[{"name":"thenavidm","email":"n@navid.me"}],"homepage":"https://github.com/thenavidm/telegram-mcp-cli#readme","bugs":{"url":"https://github.com/thenavidm/telegram-mcp-cli/issues"},"bin":{"telegram-cli":"dist/index.js","telegram-mcp":"dist/index.js"},"dist":{"shasum":"49602513dc1c8e7ef5b48369cc8e9e97437f122f","tarball":"https://registry.npmjs.org/@thenavidm/telegram-mcp-cli/-/telegram-mcp-cli-0.4.1.tgz","fileCount":82,"integrity":"sha512-V0EhdT/zqpJ3GEOWrZif1gHmxvPPyd891qLFBsvtX38+flih0JrDUJfvr/WeVDSWXrCC00X4b/vnHQKsnjKxbg==","signatures":[{"sig":"MEYCIQD39g600fCu9LE4FGZhfJcqOkdKSGYaWmNx68KEJmFzJgIhANnX1Kdp7GvJZs0RdfJpHu7yeFCoT5gB29MIqWzPCBoQ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":376013},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"0cacf9d20ab5723909766350b08ead5169dc45dd","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"thenavidm","email":"n@navid.me"},"repository":{"url":"git+https://github.com/thenavidm/telegram-mcp-cli.git","type":"git"},"_npmVersion":"10.9.8","description":"Telegram MCP server and CLI for Claude Code and AI agents. 74 tools for chats, history, search, sending, media, contacts, groups, admin, topics, reactions, polls, folders and privacy, on your real Telegram account over MTProto.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"zod":"^3.23.8","telegram":"^2.26.22","zod-to-json-schema":"^3.24.1","@modelcontextprotocol/sdk":"^1.18.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.0","typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/telegram-mcp-cli_0.4.1_1788880282082_0.9930273548577766","host":"s3://npm-registry-packages-npm-production"}},"0.4.2":{"name":"@thenavidm/telegram-mcp-cli","version":"0.4.2","keywords":["mcp","model-context-protocol","telegram","mtproto","cli","claude","ai-agents"],"author":{"url":"https://navid.me","name":"Navid Moazzez"},"license":"MIT","_id":"@thenavidm/telegram-mcp-cli@0.4.2","maintainers":[{"name":"thenavidm","email":"n@navid.me"}],"homepage":"https://github.com/thenavidm/telegram-mcp-cli#readme","bugs":{"url":"https://github.com/thenavidm/telegram-mcp-cli/issues"},"bin":{"telegram-cli":"dist/index.js","telegram-mcp":"dist/index.js"},"dist":{"shasum":"74aaf954da57880f2b835dc7731277a866d044ab","tarball":"https://registry.npmjs.org/@thenavidm/telegram-mcp-cli/-/telegram-mcp-cli-0.4.2.tgz","fileCount":82,"integrity":"sha512-+wfYItRj/HMqCJUWC+04WQvQF6FBGMEek+yitPN7pFypu+6KjxVdRNUOhTYh4x0bLs6Ytt1+gDKbSunA3k6vpA==","signatures":[{"sig":"MEQCIAhpyUzUYag84qiddHhnzuEY0IpgJeVB32690PS5nB7sAiAR1Im3dSc/oDTLuSlpjGEysSUk3hzbfP96cJeNqjlZqQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":376329},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"a97e346ab3be7399c52d006ee163d50ca5d2aef6","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"thenavidm","email":"n@navid.me"},"repository":{"url":"git+https://github.com/thenavidm/telegram-mcp-cli.git","type":"git"},"_npmVersion":"10.9.8","description":"Telegram MCP server and CLI for Claude Code and AI agents. 74 tools for chats, history, search, sending, media, contacts, groups, admin, topics, reactions, polls, folders and privacy, on your real Telegram account over MTProto.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"zod":"^3.23.8","telegram":"^2.26.22","zod-to-json-schema":"^3.24.1","@modelcontextprotocol/sdk":"^1.18.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.0","typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/telegram-mcp-cli_0.4.2_1788880809461_0.5007304889462587","host":"s3://npm-registry-packages-npm-production"}},"0.4.3":{"name":"@thenavidm/telegram-mcp-cli","version":"0.4.3","keywords":["mcp","model-context-protocol","telegram","mtproto","cli","claude","ai-agents"],"author":{"url":"https://navid.me","name":"Navid Moazzez"},"license":"MIT","_id":"@thenavidm/telegram-mcp-cli@0.4.3","maintainers":[{"name":"thenavidm","email":"n@navid.me"}],"homepage":"https://github.com/thenavidm/telegram-mcp-cli#readme","bugs":{"url":"https://github.com/thenavidm/telegram-mcp-cli/issues"},"bin":{"telegram-cli":"dist/index.js","telegram-mcp":"dist/index.js"},"dist":{"shasum":"93b3c63ee68ba5f0995feb41a9d86c8390b28710","tarball":"https://registry.npmjs.org/@thenavidm/telegram-mcp-cli/-/telegram-mcp-cli-0.4.3.tgz","fileCount":82,"integrity":"sha512-fn8WAcv8BSTFQaFWawXMlYNvTSO5VWOiNLr1YKn5AD04AaH7sc/RBVJ6KCBq5y8/MroICjXjP2f1PwAV2TOs0w==","signatures":[{"sig":"MEQCIHj2Fb/aKW+zfdSP1sejmiAL2xhQnHJ8HOsubLUt9sL+AiBDfu0sg2ivDW03tY7Dh//QcA08rlBTJOWOPilqUNN7Bg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIGswEMxiE72AQRbu6CdMMN9OvF3Bh+SYT7aJ1k+tModxAiAbIJBr41mKGWzKqMjD/roHofJ2E5O64U26zAObpZABcw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@thenavidm%2ftelegram-mcp-cli@0.4.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":382723},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"7e9a19770b49930a35df8b59a4577db0a82f1316","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"thenavidm","email":"n@navid.me"},"repository":{"url":"git+https://github.com/thenavidm/telegram-mcp-cli.git","type":"git"},"_npmVersion":"10.9.8","description":"Telegram MCP server and CLI for Claude Code, Codex and AI agents. 74 tools for chats, history, search, sending, media, contacts, groups, admin, topics, reactions, polls, folders and privacy, on your real Telegram account over MTProto.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"zod":"^3.23.8","telegram":"^2.26.22","zod-to-json-schema":"^3.24.1","@modelcontextprotocol/sdk":"^1.18.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.0","typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/telegram-mcp-cli_0.4.3_1790491868197_0.9504454142254855","host":"s3://npm-registry-packages-npm-production"}},"0.4.4":{"name":"@thenavidm/telegram-mcp-cli","version":"0.4.4","keywords":["mcp","model-context-protocol","telegram","mtproto","cli","claude","ai-agents"],"author":{"url":"https://navid.me","name":"Navid Moazzez"},"license":"MIT","_id":"@thenavidm/telegram-mcp-cli@0.4.4","maintainers":[{"name":"thenavidm","email":"n@navid.me"}],"homepage":"https://github.com/thenavidm/telegram-mcp-cli#readme","bugs":{"url":"https://github.com/thenavidm/telegram-mcp-cli/issues"},"bin":{"telegram-cli":"dist/index.js","telegram-mcp":"dist/index.js","telegram-mcp-cli":"dist/npx.js"},"dist":{"shasum":"ddc5a3b014ab656110fcb9a01a468704c511fd4b","tarball":"https://registry.npmjs.org/@thenavidm/telegram-mcp-cli/-/telegram-mcp-cli-0.4.4.tgz","fileCount":85,"integrity":"sha512-lgzsSc+TnuWg1b9EEulN8GEsXnfIjx7lNBTYZevuBSlnYj+2zCu4PEowkJ5JmazP0Vrr4fwzca5YZvjFpjfiZg==","signatures":[{"sig":"MEUCIE6dnvUvmHlEapejLEst4eHnI3zRc7RIHPM72HIoMvPlAiEA75dFQNzIWiUGpB8RXxRY1KRSL0VoEL0MpG5O3i3LNs8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIDkzCoq16IIMXD9zEocHoSxmXu+noD/OL6aySqXnB2jMAiALDIO2mrYksUWwS7QwEo0beD12VicO34hGCMTd/LmEcQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@thenavidm%2ftelegram-mcp-cli@0.4.4","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":383497},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"c0c09a917e394776c6db8f7720e81c9f2310b420","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"thenavidm","email":"n@navid.me"},"repository":{"url":"git+https://github.com/thenavidm/telegram-mcp-cli.git","type":"git"},"_npmVersion":"10.9.9","description":"Telegram MCP server and CLI for Claude Code, Codex and AI agents. 74 tools for chats, history, search, sending, media, contacts, groups, admin, topics, reactions, polls, folders and privacy, on your real Telegram account over MTProto.","directories":{},"_nodeVersion":"22.23.3","dependencies":{"zod":"^3.23.8","telegram":"^2.26.22","zod-to-json-schema":"^3.24.1","@modelcontextprotocol/sdk":"^1.18.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.0","typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/telegram-mcp-cli_0.4.4_1791141310415_0.542225838441635","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"_id":"@thenavidm/telegram-mcp-cli@0.5.0","bin":{"telegram-cli":"dist/index.js","telegram-mcp":"dist/index.js","telegram-mcp-cli":"dist/npx.js"},"bugs":{"url":"https://github.com/thenavidm/telegram-mcp-cli/issues"},"dist":{"shasum":"0df9ece9a03f154a9247fa3bfd7482e8426c6a3d","tarball":"https://registry.npmjs.org/@thenavidm/telegram-mcp-cli/-/telegram-mcp-cli-0.5.0.tgz","fileCount":76,"integrity":"sha512-wZqhu5EmneXdXQfdp/viPaKOhbUKb9q/fYtoEzBVmME5qcyJks8UHbOFC2tRehg0yEjMz7B8YatVDUOuFsnmpg==","signatures":[{"sig":"MEUCIFOO6ij7Mn9QzUrlyeKnMboXGushaR3yXmq53Q44oobJAiEAzv6sHEdawdaYyDbe/TF36pJDbuiQbW6U33xFGSnyQLA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDMBCWdQi+Sa1wxPOW+pAbnUwWAeTcd+DNhKpMvIxyX3gIgNcB5vYflk4b+0s8LI9RGqmT/c68Cmzj8d3rTDLFGj+I="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@thenavidm%2ftelegram-mcp-cli@0.5.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":330022},"main":"./dist/index.js","name":"@thenavidm/telegram-mcp-cli","type":"module","types":"./dist/index.d.ts","author":{"url":"https://navid.me","name":"Navid Moazzez"},"engines":{"node":">=22"},"gitHead":"8031555acebf74c6931158a0a9cfaf04918cae29","license":"MIT","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"version":"0.5.0","_npmUser":{"name":"thenavidm","email":"n@navid.me"},"homepage":"https://github.com/thenavidm/telegram-mcp-cli#readme","keywords":["mcp","model-context-protocol","telegram","mtproto","cli","claude","ai-agents"],"repository":{"url":"git+https://github.com/thenavidm/telegram-mcp-cli.git","type":"git"},"_npmVersion":"10.9.9","description":"Telegram MCP server and CLI for Claude Code, Codex and AI agents. 74 tools for chats, history, search, sending, media, contacts, groups, admin, topics, reactions, polls, folders and privacy, on your real Telegram account over MTProto.","directories":{},"maintainers":[{"name":"thenavidm","email":"n@navid.me"}],"_nodeVersion":"22.23.3","dependencies":{"telegram":"^2.26.22","@thenavidm/slipway":"^0.1.24"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.0","typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/telegram-mcp-cli_0.5.0_1791206021083_0.5749381642794951"}}},"time":{"created":"2026-09-07T18:53:31.381Z","modified":"2026-10-05T13:13:41.758Z","0.1.0":"2026-09-07T18:53:31.741Z","0.2.0":"2026-09-07T19:34:29.635Z","0.3.0":"2026-09-07T19:45:36.574Z","0.4.0":"2026-09-07T20:00:47.404Z","0.4.1":"2026-09-08T15:11:22.247Z","0.4.2":"2026-09-08T15:20:09.603Z","0.4.3":"2026-09-27T06:51:08.346Z","0.4.4":"2026-10-04T19:15:10.518Z","0.5.0":"2026-10-05T13:13:41.188Z"},"bugs":{"url":"https://github.com/thenavidm/telegram-mcp-cli/issues"},"author":{"url":"https://navid.me","name":"Navid Moazzez"},"license":"MIT","homepage":"https://github.com/thenavidm/telegram-mcp-cli#readme","keywords":["mcp","model-context-protocol","telegram","mtproto","cli","claude","ai-agents"],"repository":{"url":"git+https://github.com/thenavidm/telegram-mcp-cli.git","type":"git"},"description":"Telegram MCP server and CLI for Claude Code, Codex and AI agents. 74 tools for chats, history, search, sending, media, contacts, groups, admin, topics, reactions, polls, folders and privacy, on your real Telegram account over MTProto.","maintainers":[{"name":"thenavidm","email":"n@navid.me"}],"readme":"<img src=\"https://cdn.navid.media/connectors/telegram-icon.png\" alt=\"Telegram\" width=\"88\">\n\n# Telegram MCP Server & CLI\n\n[![npm](https://img.shields.io/npm/v/@thenavidm/telegram-mcp-cli?color=orange&label=npm)](https://www.npmjs.com/package/@thenavidm/telegram-mcp-cli)\n[![License](https://img.shields.io/badge/License-MIT-green)](./LICENSE)\n[![YouTube](https://img.shields.io/badge/YouTube-@thenavidm-red?logo=youtube&logoColor=white)](https://youtube.com/@thenavidm?sub_confirmation=1)\n[![X](https://img.shields.io/badge/X-@thenavidm-black?logo=x)](https://x.com/thenavidm)\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-thenavidm-0A66C2?logo=linkedin&logoColor=white)](https://linkedin.com/in/thenavidm)\n\nTelegram MCP server and CLI for Claude Code, Codex and AI agents. 74 tools for chats, history, search, sending, media, contacts, groups, admin, topics, reactions, polls, folders and privacy, on your real account.\n\nOne install gives you both surfaces, the same tools under the same names,\ncovering what the app does rather than what a bot is allowed to see.\n\nMost Telegram integrations are bots, and a bot only ever receives messages sent\nto that bot. Your own conversations are invisible to it. This signs in as you\nover MTProto, so an agent can read the group you were actually talking in and\nanswer in it.\n\nBuilt and maintained by [Navid Moazzez](https://navid.me?utm_source=github&utm_medium=readme&utm_campaign=telegram-mcp-cli).\n\n<img src=\"https://cdn.navid.media/repos/telegram-mcp-cli.gif?v=3\" alt=\"Claude Code using the Telegram MCP server\" width=\"520\">\n\n## Two ways to use it\n\n### Command line\n\n`telegram-cli` in your terminal, for scripting, cron, pipes, or just asking a\nquick question without opening anything:\n\n```bash\ntelegram-cli                                       # every command, one line each\ntelegram-cli list-chats --unread-only --limit 10   # what needs an answer\ntelegram-cli history --peer @sarah --limit 20      # one conversation\ntelegram-cli search --query invoice                # across every chat\ntelegram-cli send --peer me --text \"note to self\"  # Saved Messages\ntelegram-cli list-chats --json | jq -r '.items[].name'\ntelegram-cli which search my messages             # find the command for a task\ntelegram-cli <command> --help                      # what any command takes\n```\n\n`--confirm` is the shell spelling of the confirmation that deleting requires.\n`--json` gives JSON, `--compact` puts it on one line, `--agent` turns on both\nwith no prompts and no color, and errors are JSON on stderr whichever you pick.\nBuilt on [Slipway](https://github.com/thenavidm/slipway), which turns one\ndefinition of each tool into the MCP server and the CLI.\n\nReads return real objects rather than rendered text, so `--json` hands you\nfields you can filter, and `--fields id,text` cuts the response before it is\never printed.\n\n### MCP server, for AI agents\n\n`telegram-mcp` is what Claude Code, Claude Desktop, Cursor and the rest launch.\nYou never run it by hand:\n\n```bash\nclaude mcp add telegram \\\n  -e TELEGRAM_API_ID=1234567 \\\n  -e TELEGRAM_API_HASH=your_hash \\\n  -e TELEGRAM_SESSION=your_session_string \\\n  -- npx -y @thenavidm/telegram-mcp-cli\n```\n\nThen just ask: _\"what did I miss in the group chats while I was asleep?\"_\n\nEvery other client is in [section 4](#4-connect-your-client-).\n\n### Which one\n\n| Where you are | What you can reach |\n|---|---|\n| An agent that can run shell commands, like Claude Code or Cursor | Both. The CLI is the cheaper one: nothing until it runs |\n| claude.ai, the Claude Desktop chat tab, or a phone | The server only. There is no shell to run a command in |\n| A terminal, a script, cron or CI | The CLI only. There is no MCP client in a shell |\n\nThey are the same program reading the same tool definitions, so anything one\ncan do, the other can.\n\n## Features\n\n74 tools. Every one is both a shell command and an MCP tool, under the same\nname; the command is the tool name with dashes.\n\nThese 13 are what the server loads by default, because they cover daily use:\n\n| Capability | CLI command | MCP tool |\n|---|---|---|\n| Who am I | `telegram-cli whoami` | `whoami` |\n| Resolve a handle or id | `telegram-cli resolve` | `resolve` |\n| List chats | `telegram-cli list-chats` | `list_chats` |\n| One chat's details | `telegram-cli get-chat` | `get_chat` |\n| Read history | `telegram-cli history` | `history` |\n| Search messages | `telegram-cli search` | `search` |\n| Send a message | `telegram-cli send` | `send` |\n| Edit a message | `telegram-cli edit` | `edit` |\n| Delete messages | `telegram-cli delete` | `delete` |\n| Forward messages | `telegram-cli forward` | `forward` |\n| Mark a chat read | `telegram-cli mark-read` | `mark_read` |\n| Download media | `telegram-cli download-media` | `download_media` |\n| Send a file | `telegram-cli send-file` | `send_file` |\n| Check your setup | `telegram-cli doctor` | not a tool |\n| Sign in once | `telegram-mcp login` | not a tool |\n\nThe other 61 cover contacts and blocking, groups and admin, reactions, pins,\npolls and scheduling, archiving, muting and drafts, chat folders, stickers,\nalbums and voice notes, forum topics, inline buttons, your own profile and your\nprivacy settings. They are always there in the CLI. `TELEGRAM_TOOLS=full` loads\nthem into the server as well, and [section 6](#6-which-surface-and-what-each-costs)\nsays what that costs.\n\nAll 74 are in [section 7](#7-tools).\n\n## Contents\n\n| | Section | |\n|---|---|---|\n| 1 | [What you can ask it](#1-what-you-can-ask-it) | Real prompts, not features |\n| 2 | [Quick install](#2-quick-install-) | Node 20 and one command |\n| 3 | [Set up your account](#3-set-up-your-account-) | api_id, api_hash, session string |\n| 4 | [Connect your client](#4-connect-your-client-) | Every client, copy and paste |\n| 5 | [Output and exit codes](#5-output-and-exit-codes) | What scripts branch on |\n| 6 | [Which surface, and what each costs](#6-which-surface-and-what-each-costs) | Measured in Claude Code, and how to spend less |\n| 7 | [Tools](#7-tools) | All 74, grouped, with the default 13 in full |\n| 8 | [Writing safely](#8-writing-safely) | Why deleting asks twice |\n| 9 | [Reading messages](#9-reading-messages) | The output format, and why |\n| 10 | [How it works](#10-how-it-works) | Architecture |\n| 11 | [Your data](#11-your-data) | What is stored and where |\n| 12 | [Risks](#12-risks) | Read this before you install |\n| 13 | [Troubleshooting](#13-troubleshooting) | When something breaks |\n| 14 | [FAQ](#14-faq-) | Including what an MCP server is |\n\n## 1. What you can ask it\n\nReal prompts, not a feature list. Each of these is one or two tool calls.\n\n> What did I miss in the group chats while I was asleep?\n\n> Find the last thing Sarah sent me about the invoice and reply that I will\n> look at it tonight.\n\n> Search every chat for the wifi password someone sent me last year.\n\n> Which conversations have unread messages, and which actually need an answer\n> rather than an emoji?\n\n> Save the PDF that Tom sent me this morning to my desktop.\n\n> Send myself a note in Saved Messages with these three links.\n\nThe reading tools are the ones worth having on. Searching a decade of chat for\na thing you half remember is what this is genuinely better at than scrolling.\n\n## 2. Quick install ⚡\n\nNode 20 or newer. Nothing else.\n\n```bash\nnpx -y @thenavidm/telegram-mcp-cli@latest --version\n```\n\nThat is the whole install. `npx` fetches it on demand, so there is nothing to\nupdate later. Prefer it on your `$PATH`?\n\n```bash\nnpm install -g @thenavidm/telegram-mcp-cli\n```\n\nInstalling needs no account. Only signing in does, which is the next section.\n\n### Before you start\n\n| You need | Check with | If missing |\n|---|---|---|\n| Node 20 or newer | `node -v` | [nodejs.org](https://nodejs.org) |\n| A Telegram account | Open the app | Any account works, no Premium needed |\n| A phone you can receive a code on | | The code arrives **in the Telegram app**, not by SMS |\n\n> [!IMPORTANT]\n> You need an api_id from [my.telegram.org](https://my.telegram.org), not a bot\n> token from BotFather. A bot cannot read your chats, which is the entire point\n> of this. [Section 3](#3-set-up-your-account-) walks through it.\n\n## 3. Set up your account 🔑\n\nThree values. The first two identify the application, the third is you.\n\n### The api_id and api_hash\n\nGo to [my.telegram.org](https://my.telegram.org), sign in with your phone\nnumber, open **API development tools**, and fill in the short form. Any app name\nand a short description are fine. You get an `api_id` and an `api_hash`.\n\nThese identify the software, not you, and they are not especially secret. They\ncannot read anything on their own.\n\n### The session string\n\n```bash\nexport TELEGRAM_API_ID=1234567\nexport TELEGRAM_API_HASH=your_hash_here\nnpx -y @thenavidm/telegram-mcp-cli login\n```\n\nIt asks for your phone number, the code Telegram sends you, and your two-step\npassword if you have one. It prints the session string on stdout and everything\nelse on stderr, so `telegram-mcp login > session.txt` captures only the string.\n\n```bash\nexport TELEGRAM_SESSION='the string it printed'\n```\n\n### What that string is\n\n**Full access to your account, and it does not expire.** It is not a token\nscoped to some permissions, it is your login. Anyone holding it can read every\nmessage you have and send as you.\n\nKeep it out of repos. Put it in your MCP client's config, which is a file only\nyou can read, rather than in a shell profile that gets committed by accident.\n\n### Revoking\n\nTelegram, **Settings → Devices**. The session shows up as a logged-in device\nand terminating it invalidates the string immediately. Do that if it leaks, or\nwhenever you stop using this, then run `login` again if you come back.\n\n## 4. Connect your client 🔌\n\n```bash\nnpm install -g @thenavidm/telegram-mcp-cli\n```\n\nOr run it without installing anything:\n\n```bash\nnpx -y @thenavidm/telegram-mcp-cli\n```\n\nNode 20 or newer.\n\n### Claude Code\n\n```bash\nclaude mcp add telegram \\\n  -e TELEGRAM_API_ID=1234567 \\\n  -e TELEGRAM_API_HASH=your_hash \\\n  -e TELEGRAM_SESSION=your_session_string \\\n  -- npx -y @thenavidm/telegram-mcp-cli\n```\n\n### Claude Desktop\n\nThe short way: download the [`.mcpb` extension](https://github.com/thenavidm/telegram-mcp-cli/releases/latest)\nfrom the latest release and double-click it. It carries its own dependencies,\nso there is no config file to edit and nothing to install first. It asks for your API ID, API hash and session string in a form, and stores them\nas sensitive fields rather than plain text in a config file.\n\nThe long way, if you would rather edit the config yourself:\n\nSettings → Developer → Edit Config, then add:\n\n```json\n{\n  \"mcpServers\": {\n    \"telegram\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@thenavidm/telegram-mcp-cli\"],\n      \"env\": {\n        \"TELEGRAM_API_ID\": \"1234567\",\n        \"TELEGRAM_API_HASH\": \"your_hash\",\n        \"TELEGRAM_SESSION\": \"your_session_string\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop afterwards.\n\n### Cursor\n\nSettings → MCP → Add new global MCP server, using the same JSON as Claude\nDesktop.\n\n### Windsurf\n\nSettings → Cascade → Model Context Protocol, same JSON shape.\n\n### VS Code\n\n```bash\ncode --add-mcp '{\"name\":\"telegram\",\"command\":\"npx\",\"args\":[\"-y\",\"@thenavidm/telegram-mcp-cli\"]}'\n```\n\nThen set the three environment variables in your shell profile, or add an `env`\nblock to the entry.\n\n### Anything else\n\nAny client that speaks MCP over stdio. The command is\n`npx -y @thenavidm/telegram-mcp-cli` with the three variables in the\nenvironment.\n\n### Docker\n\n```bash\ndocker build -t telegram-mcp .\ndocker run --rm -i \\\n  -e TELEGRAM_API_ID -e TELEGRAM_API_HASH -e TELEGRAM_SESSION \\\n  telegram-mcp\n```\n\n### Check it worked\n\n```bash\ntelegram-cli doctor\n```\n\nIt names any missing variable, says where to get it, and signs in to confirm\nthe session actually works rather than only that it is present.\n\n## 5. Output and exit codes\n\n### What gets printed\n\nReads return objects. A list comes back as `{count, next_cursor, items}`, so\npaging is a field rather than something you infer.\n\n```bash\ntelegram-cli list-chats --limit 3 --fields name,unread\n```\n\n```json\n{\n  \"count\": 3,\n  \"items\": [\n    { \"name\": \"Sarah\", \"unread\": 2 },\n    { \"name\": \"Design\", \"unread\": 14 },\n    { \"name\": \"Mum\", \"unread\": 1 }\n  ]\n}\n```\n\nErrors are JSON on stderr, with the code and often a hint:\n\n```json\n{\n  \"error\": \"Telegram rate limited this account. Wait 42s.\",\n  \"code\": \"RATE_LIMIT\",\n  \"retryAfter\": 42,\n  \"hint\": \"Flood waits are per method and get longer if you keep calling. Wait it out.\"\n}\n```\n\n### Exit codes\n\nA script branches on the number.\n\n| Code | Means |\n|---|---|\n| 0 | Fine |\n| 1 | Something unexpected went wrong |\n| 2 | Bad usage, or a write refused for want of `--confirm` |\n| 3 | No such chat, user or message |\n| 4 | The session is invalid or expired |\n| 5 | Telegram rejected the call, or forbade it |\n| 7 | Rate limited, `retry_after_seconds` says how long |\n| 10 | Nothing configured yet |\n\n## 6. Which surface, and what each costs\n\nBoth surfaces are the same program with the same 13 tools. The\ndifference is when the model pays for them. Measured in Claude Code:\n\n| | MCP server | CLI |\n|---|---|---|\n| Every message, with every tool loaded | 2,400 tokens | nothing |\n| Every message, Claude Code's default | 130 tokens | nothing |\n| When Telegram comes up | nothing more, or the tools it picks | 2,300 tokens for `SKILL.md`, once |\n| 20 messages with Telegram in 1, every tool loaded | 48,000 tokens | 2,300 tokens |\n\nClaude Code's [tool search](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search)\nis on by default: it sends only the tool names and the server instructions,\nand loads a tool's full definition when the model reaches for it. An app that\nloads every tool up front pays the first line on every message, whether\nTelegram comes up or not. With the skill added, Claude Code also lists its\none-line description, about 130 tokens.\n\nTo spend less, turn the server off when you are not using it, which in Claude\nCode is the `/mcp` panel. `TELEGRAM_READ_ONLY=1` takes the six write tools off the list, leaving seven. These numbers are the default profile's 13 tools; `TELEGRAM_TOOLS=full` lists all 74 and costs more.\nOr install the CLI and add the server on the days it earns its place.\n\nMeasured on 2026-10-05 against 0.4.4, with Claude Code 2.1.286 on Claude Opus\n5.5 (one short prompt with and without the server connected, once with\n`ENABLE_TOOL_SEARCH=false` and once with the default, the difference read from\nthe API's own usage figures; `SKILL.md` the same way) and Codex 0.159.3 on\ngpt-6.1-sol, with a placeholder session that cannot connect:\n\n| Cost | 0.4.4 | 0.5.0 |\n| --- | --- | --- |\n| Claude Code, the 13 daily tools loaded, every message | 2,820 | 2,380 |\n| Claude Code, all 74 loaded (`TELEGRAM_TOOLS=full`), every message | 14,438 | 11,868 |\n| Claude Code's default, tool search, every message (median of nine runs) | 123 | 124 |\n| `SKILL.md`, read once | 2,581 | 2,293 |\n| Codex over the CLI, one task, median of five | 72,800 | 53,221 |\n| Codex over MCP, the same task, median of five | 35,380 | 35,372 |\n\nThe task was \"find the command that searches message text across every chat,\nand the flags it requires\". Other apps and models count tokens a little\ndifferently, and tool-list characters divided by four are not API usage.\n\n## 7. Tools\n\n74 tools. Each is also a shell command under the same name with dashes, so\n`list_chats` runs as `telegram-cli list-chats`.\n\nThe 13 in [the default set](#the-default-13) are documented here with their\narguments, because they are what the server loads unless you tell it otherwise.\nThe [other 61](#the-other-61) are listed by name only. Arguments move, and a\nhand-typed list of 74 signatures goes stale the day a tool is added, so ask the\nbinary instead:\n\n```bash\ntelegram-cli                    # all 74, one line each, writes marked\ntelegram-cli <command> --help   # its arguments, derived from the schema\ntelegram-cli schema <command>   # the JSON Schema an MCP client receives\n```\n\nTwo things hold across all of them. Every list tool takes `fields` for\nprojection and a `limit` that is clamped rather than trusted. Writes are marked\n`*`, and the irreversible ones are marked `!` and refuse to run without\nconfirmation. Those are the same marks the bare command prints.\n\n`peer` is the same everywhere: a `@username`, a numeric id, or `me` for Saved\nMessages.\n\n### The default 13\n\nWhat `TELEGRAM_TOOLS=core` advertises, which is the default: about 2,400\ntokens a message in an app that loads every tool, measured in Claude Code.\n\n#### Account\n\n| Tool | Arguments | What it does |\n|---|---|---|\n| `whoami` | none | Which account this session is signed in as |\n| `resolve` | `peer` | A @username, phone or id to something you can act on |\n\n#### Chats\n\n| Tool | Arguments | What it does |\n|---|---|---|\n| `list_chats` | `limit`, `unread_only`, `kind`, `fields` | Recent conversations, newest first |\n| `get_chat` | `peer` | One chat: name, kind, username, member count |\n\n#### Reading\n\n| Tool | Arguments | What it does |\n|---|---|---|\n| `history` | `peer`, `limit`, `before_id`, `full`, `fields` | Messages from one chat, newest first |\n| `search` | `query`, `peer`, `limit`, `fields` | Search text in one chat or everywhere |\n| `download_media` | `peer`, `message_id`, `dir` | Save a photo, video, document or voice note |\n\n#### Writing\n\n| Tool | Arguments | What it does |\n|---|---|---|\n| `send` * | `peer`, `text`, `reply_to`, `silent` | Send a message. Posts as you |\n| `send_file` * | `peer`, `path`, `caption` | Send a local file |\n| `edit` * | `peer`, `message_id`, `text` | Change a message you sent |\n| `forward` * | `from`, `to`, `message_ids` | Forward between chats |\n| `mark_read` * | `peer` | Clear a chat's unread count |\n| `delete` ! | `peer`, `message_ids`, `revoke`, `confirm` | Delete messages. Cannot be undone |\n\n### The other 61\n\nAlways reachable from the CLI, where an unused command costs nothing.\n`TELEGRAM_TOOLS=full` loads them into the server too, at about 11,900 tokens a\nmessage in an app that loads every tool.\nSee [section 6](#6-which-surface-and-what-each-costs) before you do.\n\n#### Contacts and people\n\n| Tool | What it does |\n|---|---|\n| `list_contacts` | List contacts |\n| `search_contacts` | Search contacts and users |\n| `get_user` | Get a user's profile |\n| `list_blocked` | List blocked users |\n| `add_contact` * | Add a contact |\n| `block` * | Block someone |\n| `unblock` * | Unblock someone |\n| `delete_contact` ! | Remove a contact |\n\n#### Groups, channels and admin\n\n| Tool | What it does |\n|---|---|\n| `get_participants` | List members of a chat |\n| `get_full_chat` | Full details of a chat |\n| `create_group` * | Create a group or channel |\n| `join_chat` * | Join a chat |\n| `invite_to_chat` * | Add people to a chat |\n| `invite_link` * | Get or create an invite link |\n| `set_admin` * | Promote or demote an admin |\n| `edit_chat` * | Change a chat's title or description |\n| `leave_chat` ! | Leave a chat |\n| `set_banned` ! | Ban or unban someone |\n\n#### Reactions, pins, polls and scheduling\n\n| Tool | What it does |\n|---|---|\n| `get_pinned` | List pinned messages |\n| `get_reactions` | Who reacted to a message |\n| `get_scheduled` | List scheduled messages |\n| `message_link` | Get a link to a message |\n| `pin` * | Pin or unpin a message |\n| `react` * | React to a message |\n| `create_poll` * | Send a poll |\n| `delete_scheduled` ! | Cancel scheduled messages |\n\n#### Organizing your chat list\n\n| Tool | What it does |\n|---|---|\n| `common_chats` | Chats you share with someone |\n| `search_public` | Search public chats |\n| `list_drafts` | List unsent drafts |\n| `archive` * | Archive or unarchive a chat |\n| `mute` * | Mute or unmute a chat |\n| `save_draft` * | Save or clear a draft |\n| `delete_history` ! | Delete a chat's history |\n\n#### Chat folders\n\n| Tool | What it does |\n|---|---|\n| `list_folders` | List chat folders |\n| `get_folder` | One folder's contents |\n| `create_folder` * | Create a chat folder |\n| `update_folder` * | Rename a folder or change what is in it |\n| `reorder_folders` * | Reorder chat folders |\n| `delete_folder` ! | Delete a chat folder |\n\n#### More media\n\n| Tool | What it does |\n|---|---|\n| `list_sticker_sets` | List your sticker sets |\n| `search_gifs` | Search GIFs |\n| `media_info` | Describe a message's media |\n| `transcribe_voice` | Transcribe a voice message |\n| `send_sticker` * | Send a sticker or GIF |\n| `send_album` * | Send several photos as one album |\n| `send_contact` * | Share a contact card |\n| `send_voice` * | Send a voice note |\n\n#### Forum topics and inline buttons\n\n| Tool | What it does |\n|---|---|\n| `list_topics` | List forum topics |\n| `list_buttons` | List a message's inline buttons |\n| `create_topic` * | Create a forum topic |\n| `edit_topic` * | Rename, close or reopen a topic |\n| `enable_topics` * | Turn forum topics on or off |\n| `press_button` * | Press an inline button |\n\n#### Your profile and privacy\n\n| Tool | What it does |\n|---|---|\n| `list_profile_photos` | List profile photos |\n| `get_privacy` | Read your privacy settings |\n| `export_contacts` | Export every contact |\n| `update_profile` * | Update your profile |\n| `set_profile_photo` * | Set your profile photo |\n| `set_privacy` * | Change a privacy setting |\n| `import_contacts` * | Import contacts in bulk |\n| `delete_profile_photo` ! | Delete your current profile photo |\n\n## 8. Writing safely\n\nWrites are on, and guarded. Shipping no writes is not safety, it just moves the\nwork back to you. Shipping them unguarded is worse, because `send` posts as you\nto a real person and `delete` with revoke removes messages for everyone in the\nchat, not only your copy.\n\nSo: reversible writes run. Each irreversible one, `delete` and the seven\nothers in the full set, asks first. Over MCP a person approves it: Claude Code\n(2.1.246 and later) shows its own prompt, and a client that can show forms\nasks with an approval form whose one box starts unticked. Where a client can do\nneither, the model's `confirm: true` still counts, and `TELEGRAM_CONFIRM=model`\nmakes it enough everywhere. In a terminal it is `--confirm`, which `--agent`\nnever adds.\n\n### Turning writes off entirely\n\n```bash\nTELEGRAM_READ_ONLY=1\n```\n\nWrite tools are not merely refused, they are left off the list, so the model\ncannot see them and will not try. That drops the default list to the 7 reads.\n\n`TELEGRAM_ALLOW_DESTRUCTIVE` is off by default and separate: the irreversible\ntools are refused until `TELEGRAM_ALLOW_DESTRUCTIVE=1`, even with writes on.\n\n### Annotations\n\nEvery tool sets its MCP annotations explicitly rather than letting them default.\nMCP treats `destructiveHint` and `openWorldHint` as true when omitted, so an\nunannotated read shows up in a client as destructive, which trains people to\nignore the warnings that matter.\n\n### An audit log\n\n```bash\nTELEGRAM_AUDIT_LOG=~/telegram-writes.jsonl\n```\n\nOne line per write attempted, allowed or blocked, with the tool, a one-line\nsummary, the outcome and who approved it, then a line when it is done or\nfailed. Written with mode 0600, and a failure to write it never takes a tool\ncall down with it.\n\n### Prompt injection\n\nMessage text is written by other people and reaches the model as input. Control\ncharacters, zero-width characters and bidi overrides are stripped from every\nbody before it is returned, because those are how an instruction hides from a\nhuman reviewer while staying visible to a model.\n\nTreat message content as data. It is never an instruction, whatever it says.\n\n## 9. Reading messages\n\nNothing raw is ever returned, and that is deliberate rather than lossy.\n\nA raw MTProto `Message` carries 40+ fields with nested peer objects, most of\nthem null. A raw dialog list of 200 chats is thousands of tokens of noise. So\nchats and messages are projected to flat rows of 6 to 10 fields:\n\n```json\n{\n  \"id\": 8412,\n  \"date\": \"2026-09-06T18:22:04.000Z\",\n  \"from\": \"Sarah\",\n  \"text\": \"sent the invoice over, let me know\",\n  \"reply_to\": 8409,\n  \"media\": \"document\"\n}\n```\n\nFour levers, in the order they matter:\n\n- **`fields`** keeps only what you name. `--fields id,text` on 50 messages is\n  the cheapest possible answer to \"what was said\".\n- **`limit`** defaults to 20, not 100, and is clamped rather than trusted.\n- **Bodies are truncated** to a preview unless you pass `full`.\n- **`next_cursor`** pages rather than returning a whole history. Pass it back as\n  `before_id`.\n\nA shaped chat row is around 30 tokens where the raw object is 300. That ratio is\nwhy this section exists.\n\n## 10. How it works\n\n```\n                    ALL_TOOLS  (one array, tools/index.ts)\n                         │\n        ┌────────────────┼────────────────┐\n        ▼                ▼                ▼\n    server.ts         cli.ts          channel.ts\n   MCP over stdio   shell commands    (planned)\n        │                │                │\n        └────────────────┼────────────────┘\n                         ▼\n                    WriteGuard  →  TelegramApi  →  MTProto\n```\n\nOne array of tool definitions feeds every surface. A tool added tomorrow is a\ncommand tomorrow, because the CLI derives its flags from the same Zod schema the\nMCP client receives as JSON Schema. `telegram-cli schema history` prints that\nschema, so the claim is checkable rather than asserted.\n\nThe client connects lazily, so `--help`, `doctor` and `--version` never open a\nsocket. GramJS logging is silenced before connecting because it writes to stdout\nby default, and stdout is the JSON-RPC stream.\n\n## 11. Your data\n\nNothing leaves your machine except calls to Telegram's own servers. There is no\nbackend here, no account to create, and no telemetry.\n\n| What | Where |\n|---|---|\n| Your session string | Wherever you put it. Never written to disk by this tool |\n| The audit log | Only if you set `TELEGRAM_AUDIT_LOG`, at that path, mode 0600 |\n| Downloaded media | Where you asked for it, default the working directory |\n| Message content | Held in memory for the length of one call |\n\n`telegram-mcp login` prints the session on stdout and nothing else, precisely so\nthat you decide where it lands rather than the tool choosing for you.\n\n## 12. Risks\n\nWorth reading before you install, not after.\n\n**The session string is your account.** Not a scoped token. If it leaks,\nwhoever has it can read everything and send as you, until you revoke it under\nSettings → Devices.\n\n**An agent with this connected can message real people.** That is the point,\nand it is also the risk. `TELEGRAM_READ_ONLY=1` exists for when you are pointing\nsomething you do not fully trust at it.\n\n**Message text is untrusted input.** Sanitising helps and is not a guarantee.\nAnything you would not want a model to act on unquestioned should not be in a\nchat it can read.\n\n**Telegram rate limits hard.** `FLOOD_WAIT` on a new session is normal, the\nwaits get longer if you keep calling, and an automated retry loop can get an\naccount limited for hours. The error carries `retryAfter` so a caller can wait\nthe right amount instead of guessing.\n\n**Automating a user account is not what a bot account is.** Telegram's terms\nallow user clients, but bulk or spammy behaviour through one is what gets\naccounts limited. This is built for reading your own chats and answering them.\n\n## 13. Troubleshooting\n\n| Symptom | Cause and fix |\n|---|---|\n| `not_configured`, exit 10 | One of the three variables is missing. `telegram-cli doctor` names it |\n| `auth`, exit 4 | Session revoked or expired. Run `login` again |\n| `rate_limited`, exit 7 | Flood wait. `retry_after_seconds` says how long. Wait, do not retry |\n| `not_found` on a peer | Use `resolve` or `list_chats` to get a valid id first |\n| The server starts then exits | Usually a bad session string. `doctor` connects and will say so |\n| Garbled JSON-RPC in a client | Something is writing to stdout. Open an issue with the client name |\n| `delete` refuses | By design. `TELEGRAM_ALLOW_DESTRUCTIVE=1`, then a person's approval or `--confirm` |\n\n## Environment variables\n\n**Credentials**\n\n| Variable | What it is |\n|---|---|\n| `TELEGRAM_API_ID` | From my.telegram.org, API development tools |\n| `TELEGRAM_API_HASH` | Issued with the api_id, same page |\n| `TELEGRAM_SESSION` | From `telegram-mcp login`. Full account access |\n\n**Safety**\n\n| Variable | What it does |\n|---|---|\n| `TELEGRAM_READ_ONLY=1` | Leaves every write off the list, so the model cannot see one |\n| `TELEGRAM_ALLOW_DESTRUCTIVE=1` | Permits the irreversible tools at all. Off by default |\n| `TELEGRAM_CONFIRM=model` | Lets `confirm: true` alone approve an irreversible call over MCP, for an agent with no person to ask |\n| `TELEGRAM_AUDIT_LOG` | Append-only record of every write attempted, allowed or blocked |\n\n**Tuning**\n\n| Variable | What it does |\n|---|---|\n| `TELEGRAM_TOOLS` | `core` (default), `full`, or `read`. Decides context cost |\n| `TELEGRAM_TOOLSETS` | The same choice by module, comma separated: `core`, `account`, `chats`, `messages`, `media`, `contacts`, `groups`, `engage`, `organize`, `profile`, `topics`, `stickers`, `folders`, or `all`. Unlike `TELEGRAM_TOOLS`, it narrows the CLI too |\n| `TELEGRAM_SURFACE` | `search` lists three tools that find, describe and run the rest |\n| `TELEGRAM_TIMEOUT` | Per-call deadline in seconds, default 30 |\n| `TELEGRAM_TOOL_TIMEOUT_MS` | Give up on any tool after this long |\n| `TELEGRAM_DEBUG` | `1` prints debug lines on stderr |\n\n**Several accounts**\n\n| Variable | What it does |\n|---|---|\n| `TELEGRAM_SESSION_<LABEL>` | A second account, for example `TELEGRAM_SESSION_WORK`. Read and kept as a secret, but no tool chooses between accounts yet |\n\n0.4's docs said every account-scoped tool took an optional `account`; none did.\nRun one server per account until one does.\n\n**Pushing messages into a session**\n\n| Variable | What it does |\n|---|---|\n| `TELEGRAM_CHANNEL_ALLOW` | Allowlist path for `--channel`, default `~/.telegram-mcp/channel-allow.json` |\n\n```bash\ntelegram-mcp --channel\n```\n\nRuns as a Claude Code channel, pushing real Telegram messages into a session\nthat is already open. It declares `claude/channel` under the experimental\ncapabilities, where Claude Code looks for it, and tells the model to reply\nwith the `reply` tool and the `chat_id` from the event. A channel you build\nyourself is not on Claude Code's allowlist, so start Claude Code with\n`--dangerously-load-development-channels server:<the name in your MCP config>`. The official Telegram channel is a bot, so it only sees\nmessages sent to that bot. This one is backed by your account, so an event can\ncome from any chat you are actually in.\n\nNothing is forwarded until you allow a chat, which the `allow_chat` tool does.\nThat default matters: without it every message in every group you are in\nbecomes model input, which is both expensive and a prompt-injection surface.\n\nEach allowed chat can carry a persona name, and it arrives on the event as\n`persona`, so one session can answer as a different assistant depending on\nwhich chat the message came from.\n\n**Running it always on**\n\n| Variable | What it does |\n|---|---|\n| `TELEGRAM_HTTP_PORT` | Port for `--http`, default 8787 |\n| `TELEGRAM_HTTP_HOST` | Interface for `--http`, default `127.0.0.1` |\n| `TELEGRAM_HTTP_TOKEN` | Bearer token required on every HTTP request |\n| `TELEGRAM_HTTP_ALLOWED_ORIGINS` | Comma-separated browser origins allowed to call `--http`; a page from any other site is refused |\n\n```bash\ntelegram-mcp --http --port=8787\n```\n\nBinds to loopback, because a process holding a session string should not be\nreachable from the network, and refuses to bind anywhere else without\n`TELEGRAM_HTTP_TOKEN`, which would hand your account to anyone who can route to\nthe port.\n\n## Running it 24/7\n\nFor claude.ai, your phone, or the channel, the server has to be reachable when\nthe call happens. `deploy/install.sh` sets that up on a Linux box:\n\n```bash\nsudo bash deploy/install.sh\nsudo nano /etc/telegram-mcp.env\nsudo systemctl start telegram-mcp\n```\n\nOwn user, own directory, port 8788 bound to loopback only, systemd unit that\nrestarts on failure and starts on boot. Put your reverse proxy in front of\n`127.0.0.1:8788`.\n\n`telegram-mcp login` runs on your laptop, not the server: it asks for a phone\ncode interactively. Paste the session string into the env file.\n\nWorth knowing: **a Telegram session does not expire and needs no live\nconnection.** The process can be down for a month and reconnect with the same\nstring. A server buys reachability, not session survival, so if you only use\nthe CLI you do not need one at all.\n\n## Versions\n\nSee [CHANGELOG.md](CHANGELOG.md).\n\n## 14. FAQ ❓\n\n<details>\n<summary><b>What is an MCP server?</b></summary>\n\nAn MCP server is a standard way to give an AI assistant real access to a tool,\nso it can act rather than guess. You install it once, your assistant gains the\ntools, and it works in Claude, Cursor and anything else that speaks the\nprotocol. You never call the tools yourself, you just ask in plain language.\n\n</details>\n\n<details>\n<summary><b>What is the CLI?</b></summary>\n\n`telegram-cli` is the same program as the MCP server, run as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal, a script or a cron job. Every tool is a command with dashes, so `list_chats` runs as `telegram-cli list-chats`.\n\n</details>\n\n<details>\n<summary><b>Should I use the MCP server or the CLI?</b></summary>\n\nUse the MCP server in an app with no terminal, like Claude Desktop's chat. Use the CLI anywhere commands run: an agent like Claude Code, Codex or OpenCode, a script or a cron job. The MCP server's tools take up context on every message, and the CLI costs nothing until it runs.\n\n</details>\n\n<details>\n<summary><b>How is this different from a Telegram bot?</b></summary>\n\nA bot is a separate account, and it only receives messages that people send to\nthat bot. It cannot read your conversations, your groups, or anything that\nhappened before it existed.\n\nThis signs in as you, over the same protocol the official apps use. Every chat\nyou are in, all of the history, and search across it.\n\n</details>\n\n<details>\n<summary><b>Is this allowed? Will it get my account banned?</b></summary>\n\nTelegram publishes the client API at my.telegram.org specifically so people can\nbuild clients, and third-party clients are common and long-standing.\n\nWhat gets accounts limited is behaviour, not the API: bulk messaging, spam, mass\nadding people. Reading your own chats and answering them is what this is for.\nRate limits are real and the tool surfaces them rather than retrying into them.\n\n</details>\n\n<details>\n<summary><b>What is a session string and why does it need one?</b></summary>\n\nTelegram authenticates a user by sending a code to an existing session, so there\nis a one-time interactive login. What comes out is a session string, which is\nhow the tool signs in afterwards without asking again.\n\nIt is full access to the account and does not expire. Treat it exactly as you\nwould your password, and revoke it under Settings → Devices when you are done.\n\n</details>\n\n<details>\n<summary><b>Do I need a bot token from BotFather?</b></summary>\n\nNo. BotFather issues bot tokens, and a bot is the thing this deliberately is\nnot. You need an api_id and api_hash from my.telegram.org, which is a different\npage and a different kind of credential.\n\n</details>\n\n<details>\n<summary><b>Is my data sent anywhere? Who can see it?</b></summary>\n\nNothing leaves your machine except calls to Telegram. There is no backend here,\nno account to create and no telemetry. Your session sits in your client's config\nfile and the audit log, if you enable one, sits where you pointed it.\n\n</details>\n\n<details>\n<summary><b>Can it message people without me asking?</b></summary>\n\nIt only acts when a model calls a tool, and a model only calls one in response\nto something you said. The risk is not spontaneity, it is misreading: a request\nto \"reply to everyone\" doing more than you meant.\n\nThat is what the guard is for. `delete` refuses without explicit confirmation,\n`TELEGRAM_ALLOW_DESTRUCTIVE` keeps it off entirely by default, and\n`TELEGRAM_READ_ONLY=1` removes every write tool from the list.\n\n</details>\n\n<details>\n<summary><b>Why only 13 tools when other Telegram servers have 80?</b></summary>\n\nBecause an app that loads every tool up front sends every definition with every\nmessage, whether you use it or not. All 74 here measure about 14,400 tokens in\nClaude Code, against 2,800 for the 13, and more tools make tool selection worse: a model picks correctly from 13 far more reliably\nthan from 80.\n\nThe 13 cover what actually gets used. The long tail belongs in the CLI, where it\ncosts nothing until you type it.\n\n</details>\n\n<details>\n<summary><b>Can I use several Telegram accounts?</b></summary>\n\nNot yet. One session per server instance today. You can run a second instance\nwith a different session string under a different name in your client config,\nwhich works but is clumsier than it should be.\n\n</details>\n\n<details>\n<summary><b>Does it work with Telegram Premium features?</b></summary>\n\nReading and sending work the same either way. Premium-only features like longer\nmessages and larger uploads follow whatever your account already has, because\nthis is your account rather than a bot with its own limits.\n\n</details>\n\n## Questions\n\nRun into a problem or have a question? [Open an issue](https://github.com/thenavidm/telegram-mcp-cli/issues) and I will help.\n\n## About the author\n\nNavid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. He creates useful free tools, MCP servers and CLIs that creators and founders can use in their own workflows.\n\n**Links**\n\n- Personal website: [navid.me](https://navid.me?utm_source=github&utm_medium=readme&utm_campaign=telegram-mcp-cli)\n- Link in bio: [navid.bio](https://navid.bio?utm_source=github&utm_medium=readme&utm_campaign=telegram-mcp-cli)\n- Navid Media: [navid.media](https://navid.media?utm_source=github&utm_medium=readme&utm_campaign=telegram-mcp-cli)\n- YouTube: [@thenavidm](https://youtube.com/@thenavidm?sub_confirmation=1) and [@thenavidai](https://youtube.com/@thenavidai?sub_confirmation=1)\n- X: [@thenavidm](https://x.com/thenavidm)\n- Instagram: [@thenavidm](https://instagram.com/thenavidm)\n- LinkedIn: [thenavidm](https://linkedin.com/in/thenavidm)\n\nIf this is useful, star the repo and come say hi on [X](https://x.com/thenavidm).\n\n## Dependencies\n\n| Library | License | What it does |\n|---|---|---|\n| [Slipway](https://github.com/thenavidm/slipway) | Apache-2.0 | The MCP server and the CLI from one definition of each tool |\n| [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) | Apache-2.0 | The MCP protocol and its transports, through Slipway |\n| [GramJS](https://github.com/gram-js/gramjs) | MIT | The MTProto client, published as `telegram` |\n\n## License\n\n[MIT](./LICENSE). Free to use, modify, and share.\n\nNot affiliated with, endorsed by, or connected to Telegram Messenger Inc.\n\n---\n\n© 2026 [Navid Media](https://navid.media?utm_source=github&utm_medium=referral&utm_campaign=telegram-mcp-cli&utm_content=readme). Made with ❤️ by [Navid Moazzez](https://navid.me?utm_source=github&utm_medium=referral&utm_campaign=telegram-mcp-cli&utm_content=readme).\n","readmeFilename":"README.md"}