1. Home
  2. Servers
  3. Communication
  4. Telegram MCP

Server profile

Telegram MCP

Telegram MCP connects assistants to Telegram account, chat, message, contact, and media operations through Telethon. It supports multiple accounts and an optional read-only tool surface.

View repositoryInstall & configure

Server facts

Telegram MCP

Project

Author
chigwell
Repository
github.com/chigwell/telegram-mcp
License
Apache-2.0
Category
Communication

Tech

Runtime / language
pythonPython
Transports
stdio
Remote available
No
Authentication
Not specified

Activity

GitHub stars
1,833
Last commit
Data as of

Tags

  • Messaging
  • Multi Account
  • Python
  • Telegram
  • Telethon

Overview

Telegram MCP exposes a Telegram account to compatible assistants through a Python server built on Telethon. Its README describes more than eighty tools covering messages, chats, contacts, media, folders, drafts, profiles, and administration. An assistant can inspect conversation history, search messages, send or schedule responses, manage reactions, or work with groups and channels. Multiple account sessions can coexist: read operations may query every configured account, while writes require an explicit account label in multi-account mode. Telegram-controlled content is sanitized and returned as structured JSON where practical.

Setup requires Python 3.10 or newer, Telegram API credentials, and an authorized session string or file session. The README strongly warns against installing the similarly named PyPI package because it belongs to another project. Its recommended path clones this repository, installs dependencies with uv, generates a session, and runs main.py. All tools are exposed by default, but a setting can restrict registration to read-only tools. That setting does not reduce the authority of the Telegram session itself. File-path operations remain disabled until allowed roots are configured, with real-path checks and limits on sensitive media operations. Optional proxy settings route Telegram traffic through supported SOCKS, HTTP, or MTProxy connections. Session credentials therefore deserve the same care as direct access to the account.

Install & configure

Requirements

  • Python 3.10+
  • uv for this source-checkout configuration
  • Clone of chigwell/telegram-mcp with uv sync completed
  • Telegram API credentials and an authorized session
  • An MCP client
Documented launch / install command
uv --directory /full/path/to/telegram-mcp run main.py

Replace the checkout path. Generate a session using the repository session generator before starting. Do not install the unrelated telegram-mcp package from PyPI. File tools need explicitly allowed roots; read-only exposure is not an account sandbox.

Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.

Claude Desktop configuration
{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "<Telegram application API ID>",
        "TELEGRAM_API_HASH": "<Telegram application API hash>",
        "TELEGRAM_SESSION_STRING": "<Authorized Telegram session string>",
        "TELEGRAM_EXPOSED_TOOLS": "<Optional all or read-only tool exposure>"
      }
    }
  }
}

Read the Claude Desktop setup guide

Config file · Project: .cursor/mcp.json

User: ~/.cursor/mcp.json

The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.

Cursor configuration
{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "<Telegram application API ID>",
        "TELEGRAM_API_HASH": "<Telegram application API hash>",
        "TELEGRAM_SESSION_STRING": "<Authorized Telegram session string>",
        "TELEGRAM_EXPOSED_TOOLS": "<Optional all or read-only tool exposure>"
      }
    }
  }
}

Read the Cursor setup guide

Config file · Workspace: .vscode/mcp.json

For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.

VS Code configuration
{
  "servers": {
    "telegram-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "<Telegram application API ID>",
        "TELEGRAM_API_HASH": "<Telegram application API hash>",
        "TELEGRAM_SESSION_STRING": "<Authorized Telegram session string>",
        "TELEGRAM_EXPOSED_TOOLS": "<Optional all or read-only tool exposure>"
      }
    }
  }
}

Read the VS Code setup guide

Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json

Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.

Windsurf configuration
{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "<Telegram application API ID>",
        "TELEGRAM_API_HASH": "<Telegram application API hash>",
        "TELEGRAM_SESSION_STRING": "<Authorized Telegram session string>",
        "TELEGRAM_EXPOSED_TOOLS": "<Optional all or read-only tool exposure>"
      }
    }
  }
}

Read the Windsurf setup guide

Config file · Project scope: .mcp.json at the repository root

The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.

Claude Code configuration
{
  "mcpServers": {
    "telegram-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "<Telegram application API ID>",
        "TELEGRAM_API_HASH": "<Telegram application API hash>",
        "TELEGRAM_SESSION_STRING": "<Authorized Telegram session string>",
        "TELEGRAM_EXPOSED_TOOLS": "<Optional all or read-only tool exposure>"
      }
    }
  }
}

Read the Claude Code setup guide

Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.

Tools

Source: repository README. Tool descriptions are a documented snapshot, not a live capability check.

ToolWhat it does
send_fileSend a local file from an allowed filesystem root.
download_mediaDownload Telegram media within configured file-access boundaries.
upload_fileUpload a local file using configured allowed roots.
send_voiceSend a voice note from a permitted file path.
send_stickerSend a sticker using an allowed local path.
set_profile_photoSet a profile photo from a permitted local file.
edit_chat_photoChange a chat photo using a permitted local file.

Names, permissions, and defaults can change. Check the current upstream documentation before granting access.

Use cases

  • Review chat history and prepare responses.
  • Search unread messages across configured accounts.
  • Schedule messages or organize Telegram folders.
  • Manage groups, channels, and member permissions.
  • Send or download media within approved file roots.

Strengths

  • Broad coverage of Telegram account and messaging operations.
  • Explicit multi-account routing for write operations.
  • Optional read-only tool registration and file-root restrictions.

Limitations

  • Session credentials grant normal Telegram account authority.
  • The PyPI package with the same name is unrelated.
  • File tools require allowed-root configuration.

Frequently asked questions

The README says not to: that package belongs to another project and is not this repository.

Yes. Suffixed session variables create account labels; write tools require a label when multiple accounts are configured.

No. It removes write tools from the MCP surface without reducing the session authority inside the process.

File-path tools remain disabled until allowed roots are supplied through server arguments or client Roots.

Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.

Related MCP servers

MCP Server ChatSum

Communication

Query a saved chat database and summarize matching messages through an assistant. ChatSum relies on its companion chatbot to collect messages and connects to Claude Desktop over stdio.

nodestdio1,028 GitHub stars

MCP Server for LinkedIn

Communication

Connect an AI assistant to LinkedIn through your own browser session. The server helps you research people and companies, explore jobs, and read conversations from a local installation.

pythonstdio3,897 GitHub stars

WhatsApp MCP Server

Communication

Connect an assistant to your personal WhatsApp account to search chats, inspect contacts, and send text or media. A Go bridge stores message history locally and serves a Python MCP layer.

gostdio6,633 GitHub stars

Slack MCP Server

Communication

Connect an assistant to Slack channels, threads, DMs, and user information. The server supports filtered history and search, multiple transports, and optional posting or reactions disabled by default.

gostdio1,867 GitHub stars