Telegram Cowork Plugin

Local Python project for collecting Telegram channel posts into SQLite and exposing them to Claude Cowork through a local MCP server.

The project currently includes configuration validation, SQLite schema initialization, repository methods for channels/posts, a Telethon-based sync service, tests, and a minimal MCP/plugin skeleton.

Setup

python -m venv .venv
.\.venv\Scripts\python -m pip install --upgrade pip
.\.venv\Scripts\python -m pip install -e ".[dev]"
Copy-Item .env.example .env
Copy-Item configs\channels.example.yaml configs\channels.yaml

Edit .env and configs/channels.yaml locally. Keep real Telegram credentials, session strings, SQLite databases, logs, and generated reports out of Git.

When the config file is inside configs/, relative paths such as data/... and .sessions/... are resolved from the project root. This keeps CLI and Claude Desktop MCP runs using the same local files even when Claude starts the executable from another working directory.

Validate configuration

.\.venv\Scripts\telegram-cowork --config configs\channels.yaml config-check

The command prints redacted diagnostics and never prints credential values.

Initialize SQLite

.\.venv\Scripts\telegram-cowork --config configs\channels.yaml init-db

Sync Telegram channels

.\.venv\Scripts\telegram-cowork --config configs\channels.yaml sync --since-hours 24

The sync command reads enabled channels from configs/channels.yaml, fetches messages through Telethon, and upserts posts by (channel, message_id) so repeated runs are idempotent. It prints only aggregate sync counts.

--since-hours is an explicit override. If you omit it, each channel resumes from its stored last_synced_post_at minus sync_overlap_minutes. On a fresh channel it falls back to since_hours from the config.

.\.venv\Scripts\telegram-cowork --config configs\channels.yaml sync

If Telegram is blocked or slow from the current network, tune telegram_network in configs/channels.yaml to reduce connection timeout/retries. Telethon does not automatically use the Windows global proxy for MTProto TCP connections; configure telegram_network.proxy explicitly if your proxy app exposes a local SOCKS/HTTP proxy.

Run local MCP server

.\.venv\Scripts\telegram-cowork --config configs\channels.yaml mcp-server

The MCP server runs over stdio and exposes:

• sync_channels
• list_channels
• list_recent_posts
• search_posts
• prepare_digest

Read docs/MCP.md for Claude Desktop and Claude Cowork notes.

Package Claude plugin

The installable plugin skeleton is in plugin/ and includes the telegram-digest skill plus MCP server configuration. See:

• docs/PLUGIN_INSTALL.md
• docs/cowork-plugin-notes.md
• docs/SCHEDULED_TASK_PROMPT.md
• docs/TROUBLESHOOTING.md

Run tests and lint

.\.venv\Scripts\python -m pytest
.\.venv\Scripts\python -m ruff check .

Security

Read docs/SECURITY.md before connecting a real Telegram reader account. Never commit .env, session files, auth codes, database files, logs, or generated reports.