matskevich/tg-mcp-guarded

开发工具

本页由 AI 翻译，技术细节请以原文为准。查看原文

10 stars 20 forks 质量 80 趋势 38MIT

Repository Install

dual-plane telegram mcp: read-only analytics + guarded actions with anti-spam and block-risk controls

概览

начать агенту: промпт, скиллы и примеры · установка на своём аккаунте персональные продажи gconf: scoped skill и обновления MCP server + Python library for Telegram API with built-in rate limiting, anti-spam protection, and session management. Dual-plane Telegram MCP: read-only analytics + guarded write actions with anti-spam and block-risk controls. provides: - — Read and Actions profiles with different risk levels - — Token bucket (4 RPS), daily quotas (20 DM/day, 20 joins/day) - — optional shared RPS limiter across projects/processes - — FLOOD_WAIT retry with exponential backoff - — auto cooldown after long FLOOD_WAIT events - — chmod 700/600 hardening for session files - — participants, messages, groups, dialogs tg-mcp-guarded emphasizes what makes this project different from generic Telegram MCP integrations: - — separate tgmcp-read and tgmcp-actions servers - — write operations only via Action MCP policy gates - — anti-flood, anti-spam, retry/backoff, and circuit-breaker...

README

以下为原文 README 节选，完整内容请查看原文。

tg-mcp (tg-mcp-guarded)

начать агенту: промпт, скиллы и примеры · установка на своём аккаунте

персональные продажи gconf: scoped skill и обновления

MCP server + Python library for Telegram API with built-in rate limiting, anti-spam protection, and session management.

Dual-plane Telegram MCP: read-only analytics + guarded write actions with anti-spam and block-risk controls.

What is this?

tg-mcp provides:

Two MCP servers — Read and Actions profiles with different risk levels
Rate limiting — Token bucket (4 RPS), daily quotas (20 DM/day, 20 joins/day)
Multi-process protection — optional shared RPS limiter across projects/processes
Anti-spam — FLOOD_WAIT retry with exponential backoff
Circuit breaker — auto cooldown after long FLOOD_WAIT events
Session security — chmod 700/600 hardening for session files
Data exporters — participants, messages, groups, dialogs

Positioning

tg-mcp-guarded emphasizes what makes this project different from generic Telegram MCP integrations:

Risk split by design — separate tgmcp-read and tgmcp-actions servers
Guarded write path — write operations only via Action MCP policy gates
Block-risk awareness — anti-flood, anti-spam, retry/backoff, and circuit-breaker defaults

Quick Start

# Install dependencies
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Configure
cp .env.sample .env
# Edit .env with your TG_API_ID, TG_API_HASH

# Run tests
PYTHONPATH=tganalytics:. python3 -m pytest tests/ -q

Developer Setup Shortcut

For local development, you can bootstrap everything (env sync, dependencies, and required data directories) with one command:

make dev-setup

Before opening a PR, run the standard repository checks:

make dev-check

Session Bootstrap (Auth)

read profile remains write-safe, but initial Telegram login requires auth requests. Use dedicated auth bootstrap helpers:

# Interactive code login (enables auth-only requests internally)
PYTHONPATH=tganalytics:. python3 tganalytics/examples/create_telegram_session.py \
  --session-name my_read

# QR login fallback (more reliable when code is delayed)
PYTHONPATH=tganalytics:. python3 scripts/create_session_qr.py \
  --session-name my_read

Where to find login code:

Telegram app in-app message (most common, SentCodeTypeApp)
Archived chats folder
Another active device/session notifications

Secrets Without `.env` (Keychain / Secret Provider)

TG_API_ID and TG_API_HASH can be loaded from secrets providers:

TG_SECRET_PROVIDER=env (default): read plain env values
TG_SECRET_PROVIDER=keychain: load from macOS Keychain
TG_SECRET_PROVIDER=command: load from command outputs

macOS Keychain example

security add-generic-password -a TG_API_ID -s tg-mcp -w "12345678" -U

在 GitHub 查看完整 README

安装

This server does not publish a one-line install command.

Open the repository installation guide 新手？先看 mcpskill.org 教程 →

配置

{
  "mcpServers": {
    "tgmcp-read": {
      "command": "path/to/tg-mcp/venv/bin/python3",
      "args": ["path/to/tg-mcp/tganalytics/mcp_server_read.py"],
      "env": {
        "PYTHONPATH": "path/to/tg-mcp/tganalytics:path/to/tg-mcp",
        "TG_SESSIONS_DIR": "path/to/tg-mcp/data/sessions",
        "TG_SESSION_PATH": "path/to/tg-mcp/data/sessions/my_account_ro.session",
        "TG_READ_SESSION_PATH": "path/to/tg-mcp/data/sessions/my_account_ro.session",
        "TG_ACTIONS_SESSION_PATH": "path/to/tg-mcp/data/sessions/my_account.session",
        "TG_SESSION_PATH_CONFLICT_MODE": "warn",
        "TG_SESSION_CONFLICT_REGISTRY_FILE": "path/to/tg-mcp/data/anti_spam/session_registry.json",
        "TG_EXPECTED_USERNAME": "my_main_account",
        "TG_ALLOW_SESSION_SWITCH": "0",
        "TG_BLOCK_DIRECT_TELETHON_WRITE": "1",
        "TG_ALLOW_DIRECT_TELETHON_WRITE": "0",
        "TG_ENFORCE_ACTION_PROCESS": "1",
        "TG_DIRECT_TELETHON_WRITE_ALLOWED_CONTEXTS": "actions_mcp",
        "TG_WRITE_CONTEXT": "read_mcp",
        "TG_ACTION_PROCESS": "0",
        "TG_SESSION_RUNTIME_MODE": "copy",
        "TG_RECEIVE_UPDATES": "0",
        "TG_SESSION_LOCK_MODE": "shared",
        "TG_GLOBAL_RPS_MODE": "shared"
      }
    },
    "tgmcp-actions": {
      "command": "path/to/tg-mcp/venv/bin/python3",
      "args": ["path/to/tg-mcp/tganalytics/mcp_server_actions.py"],
      "env": {
        "PYTHONPATH": "path/to/tg-mcp/tganalytics:path/to/tg-mcp",
        "TG_SESSIONS_DIR": "path
…