Telegram MCP Readonly

Search Telegram chats and messages from any MCP client. Read conversation history and download attachments without sending messages or changing chats.

Quick start · Client setup · Documentation · Security

What it does

Related MCP server: telegram-mcp

Install

You need Python 3.10+, uv, a Telegram account, and API credentials from my.telegram.org/apps.

git clone https://github.com/mshykhov/telegram-mcp-readonly.git
cd telegram-mcp-readonly
uv sync --frozen
uv run python setup_readonly.py

Sign in by scanning the QR code with Telegram. Read-only mode is enabled by default. Keep the generated .env and session files private.

Clone this repository: the telegram-mcp package on PyPI is a different project.

Connect an MCP client

For one local client, configure a stdio server:

{
  "mcpServers": {
    "telegram-readonly": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp-readonly",
        "run",
        "telegram-mcp"
      ]
    }
  }
}

Configuration and documentation

The setup script writes the required configuration. See .env.example for optional proxy, multi-account, event-feed, and device settings. The documentation map includes the shared-service runbook for macOS installations shared by several clients.

Dependency updates

Renovate uses the shared update policy for Python dependencies and uv.lock, npm tooling, Docker images, and GitHub Actions. Minor, patch, and pin updates merge automatically after all required CI checks pass against the current main. Major updates require dashboard approval and manual merging; weekly lock-file maintenance also stays manual. MCP stays below v2 until a reviewed migration.

Python application dependencies are pinned so each PR updates exactly the advertised version. Renovate refreshes branches when main advances, and CI blocks its PRs if lock-file generation fails. Eligible updates can merge at any time after the shared release-age checks pass.

Fork maintenance

This fork adds the audited read-only tool boundary, confined attachment downloads, QR setup, and a shared local service. The original upstream commits retain their authors and dates. Upstream changes through 5d7f0a7 are integrated, including rich-message reading, custom emoji metadata, safer error logging, and session locks.

New upstream tools remain excluded from strict mode until reviewed. Voice transcription and its cache are disabled in strict mode, including automatic transcription during history reads.

Attribution and license

This project is based on chigwell/telegram-mcp and is licensed under the Apache License 2.0.