Skip to content
Conduit

mcp server

telegram-mcp-readonly

Read-only Telegram MCP server. Search chats, read messages, and download attachments from any MCP client.

mshykhov/telegram-mcp-readonlycommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

  • uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "telegram-mcp-readonly": {
      "command": "uvx",
      "args": [
        "telegram-mcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 17, 2026

Telegram MCP Readonly

Tests Docker Security Python 3.10+ License: Apache 2.0

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

CapabilityIncluded
SearchMessages across chats, account-wide search, folder filters
ReadHistory, topics, rich messages, custom emoji metadata, profiles
AttachmentsDownloads confined to one configured directory
ConnectStdio for one client; a shared local HTTP service for several clients
ProtectExplicit read-only allowlist, private session setup, sanitized results

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.

↑↓ navigate openesc close