Skip to main content
Glama
Telegram MCP

Telegram MCP

Telegram MCP — local read-only access for AI agents

The local MCP server gives Codex, Claude, and other MCP clients three tools:

Tool

Purpose

list_chats(limit, account)

List chats and unread counts

read_chat(chat, limit, account)

Latest messages of the selected chat

search_chat(chat, query, limit, account)

Search text in the selected chat

The server is read-only. There are no tools for sending, editing, or deleting messages in the code. The server runs locally via STDIO and intentionally does not provide network HTTP/SSE access.

Supported clients

  • ChatGPT/Codex Desktop;

  • Codex CLI and IDE extension;

  • Claude Code;

  • Claude Desktop;

  • any local MCP client with STDIO support.

The local server does not work directly in chatgpt.com, claude.ai, on a phone, or on another computer: these environments cannot run a process on your machine.

Related MCP server: telegram-mcp-server

What you'll need

  • Windows 10/11, macOS, or Linux;

  • Git;

  • Python 3.10+;

  • at least one supported MCP client.

Installation for beginners

1. Open a terminal

  • macOS: Command + Space → type Terminal → Enter.

  • Windows: Start menu → type PowerShell → open PowerShell.

  • Linux: press Ctrl + Alt + T or open the Terminal app.

2. Download the project

macOS/Linux:

git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git ~/telegram-mcp
cd ~/telegram-mcp

Windows PowerShell:

git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git "$env:USERPROFILE\telegram-mcp"
cd "$env:USERPROFILE\telegram-mcp"

If GitHub reports that the repository is not found, your account does not yet have access to the private repository.

3. Get your Telegram API ID and API Hash

  1. Open my.telegram.org.

  2. Sign in with your phone number.

  3. Open API development tools.

  4. Create an app, e.g. Local Telegram MCP.

  5. Save api_id and api_hash.

Do not send api_hash, the login code, or the cloud password to an AI chat.

Create a local .env.

macOS/Linux:

cp .env.example .env
nano .env

Saving in Nano: Ctrl + O → Enter → Ctrl + X.

Windows PowerShell:

Copy-Item .env.example .env
notepad .env

Fill in the file locally:

TELEGRAM_API_ID=ваш_api_id
TELEGRAM_API_HASH=ваш_api_hash

4. Install dependencies and sign in to Telegram

macOS/Linux:

bash setup.sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File setup.ps1

The script will find Python 3.10+ itself, create .venv, install dependencies, and ask for your phone number, the code from Telegram, and, if enabled, the cloud password. Enter them only in your own terminal.

Connecting to an agent

In all examples, use the absolute paths printed by the setup script. The command is Python inside .venv, the argument is telegram_mcp_server.py.

Codex CLI and ChatGPT/Codex Desktop

macOS/Linux:

codex mcp add telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
codex mcp get telegram

Windows PowerShell:

codex mcp add telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
codex mcp get telegram

In ChatGPT/Codex Desktop you can also open Settings → MCP servers → Add server, select STDIO, and specify the same Command and Arguments. After saving, click Restart. Local clients of the same Codex host share the ~/.codex/config.toml configuration.

Claude Code

macOS/Linux:

claude mcp add --transport stdio --scope user telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
claude mcp get telegram

Windows PowerShell:

claude mcp add --transport stdio --scope user telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
claude mcp get telegram

Start a new Claude Code session and type /mcp. The user scope makes the server available across different local projects of this user.

Claude Desktop

Open the Developer/MCP settings and add a local STDIO server. If your Claude Desktop version uses a JSON configuration, add the object while keeping the other servers:

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/telegram-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/telegram-mcp/telegram_mcp_server.py"]
    }
  }
}

Typical file locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json;

  • Windows: %APPDATA%\Claude\claude_desktop_config.json.

Fully restart Claude Desktop and open a new chat.

Another STDIO MCP client

Use an equivalent configuration:

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/telegram_mcp_server.py"]
    }
  }
}

Final check

Ask the agent:

Use telegram list_chats with limit=10 and show the name, type, and number of unread messages.

Do not consider the installation complete until the agent has actually returned the list of your chats.

Multiple accounts

The server supports separate local sessions default, work, personal, and others. Instructions are in docs/MULTI_ACCOUNT.md.

Instructions for AI agents

If Codex, Claude, or another agent is performing the installation, ask it to fully read docs/AGENT_SETUP.md and follow it step by step. This file contains security rules and branches for different OSes.

Security and limitations

  • .env and sessions/ are excluded from Git;

  • the .session file grants access to the account — do not copy or publish it;

  • media files are not downloaded, only the has_media flag is returned;

  • requests to Telegram are executed on behalf of your account and obey Telegram's limits;

  • do not run two operations with the same .session at the same time;

  • do not expose this server to the internet.

More: SECURITY.md.

If something doesn't work

See docs/TROUBLESHOOTING.md.

Development

.venv/bin/python -m unittest discover -s tests -v

Project structure:

File

Purpose

telegram_mcp_server.py

Three read-only MCP tools, STDIO only

telegram_ro_common.py

Loading settings and local Telethon sessions

login.py

Sign in and create a named session

setup.sh

Installation on macOS/Linux

setup.ps1

Installation on Windows

docs/AGENT_SETUP.md

Step-by-step protocol for AI agents

docs/MULTI_ACCOUNT.md

Connecting multiple accounts

docs/TROUBLESHOOTING.md

Diagnosing common issues

License

MIT — the project can be used, modified, and distributed with the copyright notice and the license text preserved.

Available Tools

14 tools
analyze_chat_activityC

Compute deterministic activity statistics; the calling agent writes narrative analysis.

Inputs: chat (required), limit, account, topic_id.

get_message_contextC

Read one message and bounded surrounding context.

Inputs: chat (required), message_id (required), after, before, +1 more.

get_unreadA

Return unread messages grouped by chat without marking them read.

Inputs: account, limit_chats, limit_per_chat.

inspect_permissionsA

Show the active profile, allowed capabilities, and physically exposed tools.

Inputs: no named parameters.

list_chat_foldersC

List Telegram chat folders without changing their configuration.

Inputs: account.

list_chatsC

List chats, stable references, unread counts, and pinned state.

Inputs: limit, account.

list_folder_chatsC

List chats visible in one Telegram folder by its numeric folder id.

Inputs: folder_id (required), limit, account.

list_forum_topicsC

List topics in a Telegram forum chat, including unread state.

Inputs: chat (required), limit, query, account.

read_chatC

Read recent messages from a chat, returned oldest-first.

Inputs: chat (required), limit, account.

read_forum_topicB

Read recent messages from one forum topic without marking it read.

Inputs: chat (required), topic_id (required), limit, account.

search_chatC

Search message text within one chat.

Inputs: chat (required), query (required), limit, account.

search_forum_topicC

Search message text inside one forum topic.

Inputs: chat (required), query (required), topic_id (required), limit, +1 more.

search_globalC

Search message text across all dialogs.

Inputs: query (required), limit, account.

telegram_diagnosticsA

Inspect local runtime/config/storage state without returning secrets or messages.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct scope or operation: search by chat/global/forum topic, list chats/folders/topics, read chat/topic/unread/context, plus analysis and diagnostics. Overlaps are minimal and descriptions clearly differentiate boundaries (e.g., read_chat vs read_forum_topic).

    Naming Consistency4/5

    Most tools follow a consistent verb_noun snake_case pattern (search_chat, list_chats, get_unread). One outlier is telegram_diagnostics, which lacks a verb and slightly breaks the pattern, but overall naming is predictable.

    Tool Count5/5

    14 tools is well-scoped for a read-only Telegram client surface, covering search, read, list, and diagnostic needs without redundant or excessive operations.

    Completeness4/5

    The read-only surface is quite complete for searching, reading, listing, and analyzing chats, including unread and forum topic support. Minor gaps remain in exposing detailed chat metadata (e.g., profile info) or any write operations, though the latter may be intentional.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Read-only Telegram access for Claude and other MCP hosts. Provides tools to list chats, read recent messages, and download media from your own Telegram account without needing an api_id/api_hash.
      5
      67 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A read-only MCP server that lets AI agents read personal Telegram chats from an allowlist of folders, with no send/edit/delete capability.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables reading Telegram chats and searching messages through natural language, connecting to MCP clients like Claude Code, Codex, and Cursor.
      26 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to interact with a personal Telegram account via MCP, offering tools for reading and searching chats, summarizing unread messages, sending and editing messages, handling files and voice transcripts, and managing groups and channels, with read-only mode by default.
      Apache 2.0