chigwell/telegram-mcp

What it solves

This project provides a bridge between AI agents (like Claude, Cursor, and other MCP-compatible clients) and Telegram. It allows an LLM to interact with your Telegram account, enabling it to read and send messages, manage chats, and handle media, effectively turning your Telegram account into a tool for the AI agent.

How it works

It implements the Model Context Protocol (MCP), exposing over 80 tools to the AI agent. It uses the Telethon library to communicate with the Telegram API. The server can be run locally via Python or Docker and supports three transport methods: stdio, streamable HTTP, and SSE. It includes a security layer to restrict which tools are exposed (e.g., read-only mode) and enforces strict file-path security to prevent unauthorized file access.

Who it’s for

Users of MCP-compatible AI agents who want to integrate their Telegram communications into their AI workflow, as well as developers who want to give their AI assistants the ability to manage Telegram accounts and messages.

Highlights

• Extensive Toolset: Over 80 tools for managing accounts, chats, messages, messages, contacts, media, and folders.
• Multi-Account Support: Ability to configure and route tool calls across multiple Telegram accounts.
• Contact Aliasing: A system to "remember" custom names for contacts to make agent interactions more natural.
• Flexible Transports: Supports stdio, http, and sse for shared server usage across multiple clients.
• Granular Security: Option to restrict tools to read-only or a specific allowlist of write tools.
• Real-time Events: An incoming event feed for callback-style delivery (specifically for Claude Code).
• Proxy Support: Built-in support for SOCKS, HTTP, and MTProxy.