telegram-mcp
installs/mo · pypistarsforks
How to install telegram-mcp?
chigwell/telegram-mcp
$git clone https://github.com/chigwell/telegram-mcpA Telegram integration for Claude, Cursor, and other MCP-compatible clients. It exposes Telegram account, chat, message, contact, media, folder, and admin operations through the Model Context Protocol using [Telethon](https://docs.telethon.dev/
README.md
| 1 | <div align="center"> |
| 2 | <img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&height=200§ion=header&text=Telegram%20MCP%20Server&fontSize=50&fontAlignY=35&animation=fadeIn&fontColor=FFFFFF&descAlignY=55&descAlign=62" alt="Telegram MCP Server" width="100%" /> |
| 3 | </div> |
| 4 | |
| 5 |  |
| 6 | [](https://opensource.org/licenses/Apache-2.0) |
| 7 | [](https://github.com/chigwell/telegram-mcp/actions/workflows/python-lint-format.yml) |
| 8 | [](https://github.com/chigwell/telegram-mcp/actions/workflows/docker-build.yml) |
| 9 | |
| 10 | A Telegram integration for Claude, Cursor, and other MCP-compatible clients. It exposes Telegram account, chat, message, contact, media, folder, and admin operations through the [Model Context Protocol](https://modelcontextprotocol.io/) using [Telethon](https://docs.telethon.dev/). |
| 11 | |
| 12 | ## 🤖 MCP in Action |
| 13 | |
| 14 | Basic Telegram MCP usage in Claude: |
| 15 | |
| 16 |  |
| 17 | |
| 18 | Asking Claude to analyze chat history and send a response: |
| 19 | |
| 20 |  |
| 21 | |
| 22 | Message sent successfully: |
| 23 | |
| 24 |  |
| 25 | |
| 26 | ## Contents |
| 27 | |
| 28 | - [What It Can Do](#what-it-can-do) |
| 29 | - [Requirements](#requirements) |
| 30 | - [Quick Start](#quick-start) |
| 31 | - [MCP Client Configuration](#mcp-client-configuration) |
| 32 | - [Multi-Account Setup](#multi-account-setup) |
| 33 | - [Device Identity](#device-identity) |
| 34 | - [Proxy Support](#proxy-support) |
| 35 | - [File Path Security](#file-path-security) |
| 36 | - [Docker](#docker) |
| 37 | - [Development](#development) |
| 38 | - [Security Notes](#security-notes) |
| 39 | - [Troubleshooting](#troubleshooting) |
| 40 | - [License](#license) |
| 41 | |
| 42 | ## What It Can Do |
| 43 | |
| 44 | The server currently includes 80+ MCP tools grouped into these areas: |
| 45 | |
| 46 | - **Accounts:** list configured accounts and route tool calls by account label. |
| 47 | - **Chats and groups:** list chats, inspect metadata, create groups/channels, join or leave chats, invite users, manage admins, bans, default permissions, slow mode, topics, invite links, common chats, read receipts, and message links. |
| 48 | - **Messages:** send, schedule, edit, delete, forward, pin, unpin, mark read, reply, search, inspect context, create polls, manage reactions, inspect inline buttons, and press inline callbacks. |
| 49 | - **Contacts:** list, search, add, delete, block, unblock, import, export, inspect direct chats, and find recent contact interactions. |
| 50 | - **Media:** send files, download media, upload files, send voice notes, stickers, GIFs, and inspect message media. |
| 51 | - **Profile and privacy:** get your own account info, update profile fields, set or delete profile photos, inspect privacy settings, get user info/photos/status, and manage bot commands. |
| 52 | - **Folders and drafts:** list, create, update, reorder, and delete Telegram folders; save, list, and clear drafts. |
| 53 | |
| 54 | All tool results that include Telegram user-controlled content are sanitized and, where practical, returned as structured JSON. |
| 55 | |
| 56 | ## Requirements |
| 57 | |
| 58 | - Python 3.10+ |
| 59 | - Telegram API credentials from [my.telegram.org/apps](https://my.telegram.org/apps) |
| 60 | - A Telegram session string or file-based session |
| 61 | - An MCP client such as Claude Desktop, Cursor, or another MCP-compatible host |
| 62 | - Optional: [uv](https://docs.astral.sh/uv/) for local development |
| 63 | |
| 64 | ## Quick Start |
| 65 | |
| 66 | > Do not install this server with `uvx telegram-mcp`, `uvx --from telegram-mcp`, |
| 67 | > or `pip install telegram-mcp`. The `telegram-mcp` name on PyPI is currently |
| 68 | > owned by a different project and does not install this repository. Passing |
| 69 | > `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`, or `TELEGRAM_SESSION_STRING` to that |
| 70 | > package can expose Telegram account credentials to unrelated third-party code. |
| 71 | |
| 72 | ### 1. Clone and Install |
| 73 | |
| 74 | ```bash |
| 75 | git clone https://github.com/chi |
People who liked this also viewed
6 picksType
- open-webuiUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)MCP ServersJul 2026
- google_workspace_mcpControl Gmail, Google Calendar, Docs, Sheets, Slides, Chat, Forms, Tasks, Search & Drive with AI - Comprehensive Google Workspace / G Suite MCP Server & CLI ToolMCP ServersJul 2026
- pagerduty-mcp-serverPagerDuty's official local MCP (Model Context Protocol) server which provides tools to interact with your PagerDuty account directly from your MCP-enabled client.MCP ServersJul 2026
- ms-365-mcp-serverA Model Context Protocol (MCP) server for interacting with Microsoft 365 and Office services through the Graph APIMCP ServersJul 2026
- GmailManage Gmail end-to-end: send, draft, reply, forward, and bulk-modify or delete messages and threads. Organize your inbox with labels, archiving, and trashing, and retrieve messages, attachments, and profile details on demand. Access and seMCP Serversrecently
- linkedin-mcp-serverOpen-source MCP server for LinkedIn. Give Claude and any MCP-compatible AI agent access to profiles, companies, jobs, and messages.MCP ServersJul 2026
