Repository navigation
v0.1.0
First release.
Telegram MCP server and CLI on a real account over MTProto, not a bot. Every chat, full history, search, sending, media and contacts.
Both surfaces from one tool array. telegram-mcp for AI clients, telegram-cli for the shell. CLI flags are derived from the same Zod schemas an MCP client receives as JSON Schema, so they cannot drift.
Tool profiles, because context is rent. Measured with a tokeniser against a real tools/list handshake: core is 13 tools and 2,218 tokens, read is 7 and 1,241. Most Telegram MCP servers ship 80+ tools, which is 15,000 to 25,000 tokens on every turn.
Responses are projected, not dumped. A raw MTProto message has 40+ fields of mostly nulls. Chats and messages come back as flat rows, bodies truncated to previews, lists paginated with a cursor, and --fields cuts further. Roughly 30 tokens per chat row against 300 raw.
Writes are on and guarded. delete refuses without confirmation and is off entirely unless TELEGRAM_ALLOW_DESTRUCTIVE=1. TELEGRAM_READ_ONLY=1 never registers a write tool at all. Control, zero-width and bidi characters are stripped from inbound message text.
npm install -g @thenavidm/telegram-mcp-cliSetup is in INSTALL.md.