{"id":47269710,"url":"https://github.com/n24q02m/better-telegram-mcp","last_synced_at":"2026-06-07T06:05:53.094Z","repository":{"id":344537654,"uuid":"1181927231","full_name":"n24q02m/better-telegram-mcp","owner":"n24q02m","description":"MCP server for Telegram (Bot API + MTProto) - composite tools optimized for AI agents","archived":false,"fork":false,"pushed_at":"2026-04-30T07:56:45.000Z","size":1521,"stargazers_count":5,"open_issues_count":10,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-30T09:22:43.081Z","etag":null,"topics":["ai-agents","ai-coding","claude","claude-code","cursor","docker","mcp","mcp-server","model-context-protocol","open-source","python","telegram","telegram-bot","telethon"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/better-telegram-mcp/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/n24q02m.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-14T20:14:48.000Z","updated_at":"2026-04-30T07:56:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/n24q02m/better-telegram-mcp","commit_stats":null,"previous_names":["n24q02m/better-telegram-mcp"],"tags_count":65,"template":false,"template_full_name":null,"purl":"pkg:github/n24q02m/better-telegram-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n24q02m%2Fbetter-telegram-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n24q02m%2Fbetter-telegram-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n24q02m%2Fbetter-telegram-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n24q02m%2Fbetter-telegram-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/n24q02m","download_url":"https://codeload.github.com/n24q02m/better-telegram-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n24q02m%2Fbetter-telegram-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32476682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"ssl_error","status_checked_at":"2026-04-30T13:12:06.837Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-coding","claude","claude-code","cursor","docker","mcp","mcp-server","model-context-protocol","open-source","python","telegram","telegram-bot","telethon"],"created_at":"2026-03-15T10:02:57.799Z","updated_at":"2026-05-08T09:02:32.364Z","avatar_url":"https://github.com/n24q02m.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Better Telegram MCP\n\nmcp-name: io.github.n24q02m/better-telegram-mcp\n\n**MCP server for Telegram with dual-mode support: Bot API (httpx) for quick bot integrations and MTProto (Telethon) for full user-account access.**\n\n\u003c!-- Badge Row 1: Status --\u003e\n[![CI](https://github.com/n24q02m/better-telegram-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/n24q02m/better-telegram-mcp/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/n24q02m/better-telegram-mcp/graph/badge.svg?token=d0fef60a-542e-4be2-9528-6e3a12931067)](https://codecov.io/gh/n24q02m/better-telegram-mcp)\n[![PyPI](https://img.shields.io/pypi/v/better-telegram-mcp?logo=pypi\u0026logoColor=white)](https://pypi.org/project/better-telegram-mcp/)\n[![Docker](https://img.shields.io/docker/v/n24q02m/better-telegram-mcp?label=docker\u0026logo=docker\u0026logoColor=white\u0026sort=semver)](https://hub.docker.com/r/n24q02m/better-telegram-mcp)\n[![License: MIT](https://img.shields.io/github/license/n24q02m/better-telegram-mcp)](https://opensource.org/licenses/MIT)\n\n\u003c!-- Badge Row 2: Tech --\u003e\n[![Python](https://img.shields.io/badge/Python-3776AB?logo=python\u0026logoColor=white)](#)\n[![Telegram](https://img.shields.io/badge/Telegram-Bot_API_+_MTProto-26A5E4?logo=telegram\u0026logoColor=white)](https://core.telegram.org)\n[![MCP](https://img.shields.io/badge/MCP-000000?logo=anthropic\u0026logoColor=white)](#)\n[![semantic-release](https://img.shields.io/badge/semantic--release-e10079?logo=semantic-release\u0026logoColor=white)](https://github.com/python-semantic-release/python-semantic-release)\n[![Renovate](https://img.shields.io/badge/renovate-enabled-1A1F6C?logo=renovatebot\u0026logoColor=white)](https://github.com/renovatebot/renovate)\n\n\u003c!-- BEGIN: AUTO-GENERATED-CROSS-PROMO --\u003e\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eSister projects from n24q02m\u003c/strong\u003e (click to expand)\u003c/summary\u003e\n\n| Project | Tagline | Tag |\n|---|---|---|\n| [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | Knowledge graph for token-efficient code reviews -- fixed search, configurabl... | MCP |\n| [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | IMAP/SMTP email server for AI agents -- 6 composite tools with multi-account ... | MCP |\n| [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Composite MCP server for Godot Engine -- 17 mega-tools for AI-assisted game d... | MCP |\n| [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | Markdown-first Notion API server for AI agents -- 10 composite tools replacin... | MCP |\n| [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | MCP server for Telegram with dual-mode support: Bot API (httpx) for quick bot... | MCP |\n| [claude-plugins](https://github.com/n24q02m/claude-plugins) | Full documentation: mcp.n24q02m.com — unified docs for all 8 servers + the mc... | Marketplace |\n| [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | Production-grade MCP server for image and video understanding + generation ac... | MCP |\n| [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |\n| [mcp-core](https://github.com/n24q02m/mcp-core) | Unified MCP Streamable HTTP 2025-11-25 transport, OAuth 2.1 Authorization Ser... | MCP |\n| [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP |\n| [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library |\n| [skret](https://github.com/n24q02m/skret) | Secrets without the server. | CLI |\n| [web-core](https://github.com/n24q02m/web-core) | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |\n| [wet-mcp](https://github.com/n24q02m/wet-mcp) | Open-source MCP Server for web search, content extraction, library docs \u0026 mul... | MCP |\n\n\u003c/details\u003e\n\u003c!-- END: AUTO-GENERATED-CROSS-PROMO --\u003e\n\n## Table of contents\n\n- [Features](#features)\n- [Status](#status)\n- [Documentation](#documentation)\n- [Tools](#tools)\n- [Security](#security)\n- [Build from Source](#build-from-source)\n- [Trust Model](#trust-model)\n- [License](#license)\n\n\n\n\u003ca href=\"https://glama.ai/mcp/servers/n24q02m/better-telegram-mcp\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/n24q02m/better-telegram-mcp/badge\" alt=\"better-telegram-mcp MCP server\" /\u003e\n\u003c/a\u003e\n\n## Features\n\n- **Dual mode** -- Bot API (httpx) for bots, MTProto (Telethon) for user accounts\n- **6 tools** with action dispatch: `message`, `chat`, `media`, `contact`, `config`, `help`\n- **Auto-detect mode** -- Set bot token for bot mode, or API credentials for user mode\n- **Web-based OTP auth** -- Browser-based authentication with remote relay support for headless environments\n- **Tool annotations** -- Each tool declares `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`\n- **MCP Resources** -- Documentation available as `telegram://docs/*` resources\n- **Security hardened** -- SSRF protection, path traversal prevention, error sanitization\n\n## Status\n\n\u003e **2026-05-02 -- Architecture stabilization update**\n\u003e\n\u003e Past months saw significant churn around credential handling and the daemon-bridge auto-spawn pattern. This caused multi-process races, browser tab spam, and inconsistent setup UX across plugins. **As of v\u0026lt;auto\u0026gt;, the architecture is stable**: 2 clean modes (stdio + HTTP), no daemon-bridge layer, no auto-spawn from stdio.\n\u003e\n\u003e Apologies for the instability period. If you encountered issues with prior versions, please update to v\u0026lt;auto\u0026gt;+ and follow the current [docs/setup-manual.md](docs/setup-manual.md) -- most prior workarounds are no longer needed.\n\u003e\n\u003e **Related plugins from the same author**:\n\u003e - [wet-mcp](https://github.com/n24q02m/wet-mcp) -- Web search + content extraction\n\u003e - [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) -- Persistent AI memory\n\u003e - [imagine-mcp](https://github.com/n24q02m/imagine-mcp) -- Image/video understanding + generation\n\u003e - [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) -- Notion API\n\u003e - [better-email-mcp](https://github.com/n24q02m/better-email-mcp) -- Email management\n\u003e - [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) -- Telegram\n\u003e - [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) -- Godot Engine\n\u003e - [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) -- Code review knowledge graph\n\u003e\n\u003e All plugins share the same architecture -- install once, learn pattern transfers.\n\n## Documentation\n\nFull docs at **[mcp.n24q02m.com/servers/better-telegram-mcp/](https://mcp.n24q02m.com/servers/better-telegram-mcp/)**:\n\n- [Setup](https://mcp.n24q02m.com/servers/better-telegram-mcp/setup/) -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json\n- [Modes overview](https://mcp.n24q02m.com/get-started/modes-overview/) -- stdio / local-relay / remote-relay / remote-oauth\n- [Multi-user setup](https://mcp.n24q02m.com/get-started/multi-user/) -- per-JWT-sub credential model\n\n**Install with AI agent** -- paste this to your AI coding agent:\n\n\u003e Install MCP server `better-telegram-mcp` following the steps at\n\u003e https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-telegram-mcp/setup-with-agent.md\n\n## Tools\n\n| Tool | Actions | Description |\n|:-----|:--------|:------------|\n| `message` | `send`, `edit`, `delete`, `forward`, `pin`, `react`, `search`, `history` | Send, edit, delete, forward messages. Pin, react, search, browse history |\n| `chat` | `list`, `info`, `create`, `join`, `leave`, `members`, `admin`, `settings`, `topics` | List and manage chats, groups, channels. Members, admin, forum topics |\n| `media` | `send_photo`, `send_file`, `send_voice`, `send_video`, `download` | Send photos, files, voice notes, videos. Download media from messages |\n| `contact` | `list`, `search`, `add`, `block` | List, search, add contacts. Block/unblock users (user mode only) |\n| `config` | `status`, `set`, `cache_clear`, `setup_status`, `setup_start`, `setup_reset`, `setup_complete` | Server status, runtime settings, cache, credential setup (relay, status, reset, complete) |\n| `help` | -- | Full documentation for any topic |\n\n### MCP Resources\n\n| URI | Content |\n|:----|:--------|\n| `telegram://docs/messages` | Message operations reference |\n| `telegram://docs/chats` | Chat management reference |\n| `telegram://docs/media` | Media send/download reference |\n| `telegram://docs/contacts` | Contact management reference |\n| `telegram://stats` | All documentation combined |\n\n## Security\n\n- **SSRF Protection** -- All URLs validated against internal/private IP ranges, DNS rebinding blocked\n- **Path Traversal Prevention** -- File paths validated, sensitive directories blocked\n- **Session File Security** -- 600 permissions, 2FA via web UI only (never stored in env vars)\n- **Error Sanitization** -- Credentials never leaked in error messages\n\n## Build from Source\n\n```bash\ngit clone https://github.com/n24q02m/better-telegram-mcp.git\ncd better-telegram-mcp\nuv sync\nuv run better-telegram-mcp\n```\n\n## Trust Model\n\nThis plugin implements **TC-NearZK** (in-memory, ephemeral). See [mcp-core/docs/TRUST-MODEL.md](https://github.com/n24q02m/mcp-core/blob/main/docs/TRUST-MODEL.md) for full classification.\n\n| Mode | Storage | Encryption | Who can read your data? |\n|---|---|---|---|\n| HTTP n24q02m-hosted (default) | In-memory `dict[sub] = MTProtoSession` | In-process only | Server process (cleared on restart) |\n| HTTP self-host | Same as hosted | Same | Only you (admin = user) |\n| stdio proxy | `~/.better-telegram-mcp/config.json` | AES-GCM, machine-bound key | Only your OS user (file perm 0600) |\n\n## License\n\nMIT -- See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn24q02m%2Fbetter-telegram-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fn24q02m%2Fbetter-telegram-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn24q02m%2Fbetter-telegram-mcp/lists"}