tgreader-mcp

tgreader-mcp

Telegram channel reader MCP server — exposes Telegram channels as MCP tools via Telethon MTProto.

Designed for use with Hermes Agent, Claude Desktop, and any MCP-compatible client.

Features

• List channels — discover channels the account is subscribed to, with optional RegExp search filter
• Read messages — fetch posts from any channel by @username or numeric ID, with date-based pagination and text search
• Multi-account — configure multiple Telegram accounts, switch between them per call
• MCP stdio transport — works out of the box with any MCP client
• Security-hardened — session files 0600, config 0600, sanitized error messages, ReDoS protection via regex library with per-match timeout

Requirements

• Python ≥ 3.11 (developed on 3.13)
• uv (recommended) or pip
• Telegram api_id / api_hash — get them at <https://my.telegram.org>

Quick start

git clone <repo-url> tgreader && cd tgreader

# Create venv and install deps (runtime + dev, editable)
./setup.sh
# or: make setup

# Activate
source .venv/bin/activate

# Login with your Telegram account
tgreader login --account main --phone +79001234567

# Check status
tgreader status

Register with Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  tgreader:
    command: /home/<user>/telegram_reader/.venv/bin/tgreader-mcp
    args: []

Install the Hermes skill

The repo ships a ready-to-use Hermes Agent skill at skills/tgreader/SKILL.md. Install it so the agent knows how to use the MCP tools:

# Copy (recommended)
cp -r skills/tgreader ~/.hermes/skills/tgreader

# Or symlink (tracks the repo, auto-updates on git pull)
ln -s ~/telegram_reader/skills/tgreader ~/.hermes/skills/tgreader

The skill teaches the agent when and how to call list_channels / read_messages, including example workflows (find vacancies, read by date range, search across channels) and pitfalls (FloodWait, session expiry, ReDoS-protected search).

Register with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "tgreader": {
      "command": "/home/<user>/telegram_reader/.venv/bin/tgreader-mcp"
    }
  }
}

MCP tools

list_channels

List Telegram channels the account is subscribed to.

| Parameter | Type | Default | Description | |------------|--------|---------|--------------------------------------------------| | account | str | — | Account name (default: configured default) | | search | str | — | RegExp pattern to filter by title/username (max 200 chars) | | limit | int | 100 | Max channels to return (max 500) |

Returns: {"count": N, "channels": [{"id", "title", "username", "type", "participants_count"}]}

read_messages

Read messages from a Telegram channel.

| Parameter | Type | Default | Description | |---------------|--------|---------|----------------------------------------------------------| | channel | str | — | Channel @username or numeric ID (required) | | account | str | — | Account name (default: configured default) | | limit | int | 20 | Max messages when offset_date is None (max 1000) | | offset_date | str | — | ISO 8601 datetime — read messages before this date | | search | str | — | RegExp pattern to filter message text (max 200 chars) |

Returns: {"count": N, "channel": {"id", "title", "username"}, "messages": [{"id", "date", "text", "views", "reactions", "media_type", "link"}]}

CLI

# Login (creates session, saves to config)
tgreader login --account main --phone +79001234567

# Account management
tgreader accounts list
tgreader accounts add --name work --phone +790011122233 --label "Work account"
tgreader accounts remove main
tgreader accounts default main

# Check session status
tgreader status
tgreader status --account work

# Start MCP server (stdio)
tgreader run
# or: tgreader-mcp

Configuration

Config lives at ~/.config/tgreader/config.json (XDG-aware):

{
  "api_id": 123456,
  "api_hash": "your_api_hash_here",
  "default_account": "main",
  "accounts": {
    "main": {
      "phone": "+79001234567",
      "label": ""
    }
  }
}

Session files (.session) are stored at ~/.config/tgreader/sessions/ with 0600 permissions.

Development

# Setup
make setup           # create .venv, install deps

# Tests
make test            # full suite (113 tests)
make test-fast       # without isolation (debugging)

# Lint
make lint            # py_compile syntax check

# Run server
make run

# Clean
make clean           # remove .venv and caches

Test suite

• 113 tests — unit + integration + BDD (pytest-bdd with Gherkin .feature files)
• BDD features cover: login flow, channel listing, message reading
• Security tests: ReDoS, error sanitization, session permissions, config validation

Project structure

tgreader-mcp/
├── src/tgreader_mcp/
│   ├── __init__.py      # version
│   ├── server.py        # FastMCP server — tool definitions
│   ├── client.py        # Telethon client — channel/message logic
│   ├── config.py        # Config load/save, account management
│   └── cli.py           # Click CLI — login, accounts, status
├── skills/tgreader/
│   └── SKILL.md         # Hermes Agent skill — tool usage guide
├── tests/
│   ├── test_server.py   # MCP tool tests
│   ├── test_client.py   # Telegram client tests
│   ├── test_config.py   # Config validation tests
│   ├── test_security.py # ReDoS, sanitization, permissions
│   ├── test_cli.py      # CLI command tests
│   ├── features/        # Gherkin .feature files
│   └── test_steps/      # pytest-bdd step implementations
├── pyproject.toml
├── Makefile
├── setup.sh
└── .python-version

Security

• Session files — 0600 permissions, stored in ~/.config/tgreader/sessions/
• Config file — 0600 permissions, atomic write (tmp → rename)
• Error sanitization — internal exceptions (Telethon, network) are caught; only safe, generalized messages reach the LLM
• ReDoS protection — regex library (not stdlib re) with 2s per-match timeout; RegexTimeoutError is caught and surfaced safely
• Config validation — full type checking on load; malformed config raises ConfigError with a clear message

License

MIT © Andrey Romanchuk