.env.example

# Telegram API Credentials (Required - get from https://my.telegram.org/apps)
TELEGRAM_API_ID=123456
TELEGRAM_API_HASH=0123456789abcdef0123456789abcdef

# --- Incoming event feed (optional, Claude Code callback mode; see README) ---
# TELEGRAM_EVENT_FEED=1
# TELEGRAM_EVENT_FEED_FILE=/path/to/incoming_feed.jsonl

# --- Single account (backward-compatible) ---
# Recommended for long-running servers: persists Telegram update state locally.
TELEGRAM_SESSION_NAME=telegram_session
# Portable setup/migration source: does not persist Telegram update state.
# If both variables are set, TELEGRAM_SESSION_STRING takes precedence, so remove
# or comment it out after running `uv run telegram-mcp-migrate-session`.
# TELEGRAM_SESSION_STRING=1231231232erfdfdffd

# --- Multiple accounts ---
# Add _<LABEL> suffix to session variables. Labels become account identifiers.
# Shared API_ID and API_HASH are used for all accounts.
# TELEGRAM_SESSION_STRING_WORK=<session string for work account>
# TELEGRAM_SESSION_STRING_PERSONAL=<session string for personal account>

# --- Session pool (same account, concurrent clients) ---
# Run several MCP clients (e.g. the desktop app AND a terminal CLI) against ONE
# Telegram account without hitting AuthKeyDuplicatedError. Telegram forbids a
# single session (auth key) being used from two IPs at once; on a VPN/dual-stack
# host two local clients can collide. List several interchangeable session
# strings (whitespace, comma or semicolon separated) and each process claims a
# free one via an advisory file lock. Generate extra sessions with
# `uv run session_string_generator.py`. Takes precedence over
# TELEGRAM_SESSION_STRING for the default account.
# TELEGRAM_SESSION_STRINGS=<session A> <session B> <session C>

# --- Session lock (optional) ---
# Before connecting, each server process takes a per-session lock so a second
# instance (e.g. a connector restart) never connects the same session while the
# first is live. exclusive (default): refuse to start if another instance still
# holds the session after TELEGRAM_LOCK_GRACE_SECONDS (default 20). shared: let
# several instances on this host use one session -- safe only when they all
# reach Telegram from the same IP; if unsure, use the pool above instead.
# TELEGRAM_SESSION_LOCK=exclusive
# TELEGRAM_LOCK_GRACE_SECONDS=20

# --- Device identity (optional) ---
# Controls how this client appears in Telegram > Settings > Devices. If unset,
# Telethon falls back to the host platform (e.g. "arm64"). Set these so the
# session keeps a stable, recognisable name across reconnects. Applied both
# when generating a session string and when the server connects.
# TELEGRAM_DEVICE_MODEL=Telegram MCP
# TELEGRAM_SYSTEM_VERSION=1.0
# TELEGRAM_APP_VERSION=1.0

# --- Expected account check (optional) ---
# Refuse to start if the session belongs to another account. _<LABEL> overrides.
# TELEGRAM_EXPECTED_USERNAME=my_username
# TELEGRAM_EXPECTED_USERNAME_WORK=my_work_username

# --- MCP tool exposure (optional) ---
# Default is all. Set to read-only to expose only tools annotated with
# readOnlyHint=True through MCP. This does not reduce Telegram session authority
# inside the server process.
# TELEGRAM_EXPOSED_TOOLS=read-only
#
# Append '+name,name' to read-only to also expose specific write tools. Every
# other write tool stays unregistered. Unknown names abort startup.
# TELEGRAM_EXPOSED_TOOLS=read-only+send_message,reply_to_message
#
# Append '-name,name' to either base (after any '+' list) to hide specific
# tools. Unknown names, or names the base already hides, abort startup.
# TELEGRAM_EXPOSED_TOOLS=all-delete_chat_history,delete_messages_bulk
# TELEGRAM_EXPOSED_TOOLS=read-only+send_message-get_participants

# --- Per-tool file extension allowlists (optional) ---
# A hardcoded allowlist already restricts send_voice/send_sticker/
# set_profile_photo/edit_chat_photo to their expected extensions; send_file
# and upload_file accept any extension by default. Use this to add, tighten,
# or replace per-tool allowlists without editing the source. Format mirrors
# TELEGRAM_EXPOSED_TOOLS: 'tool:.ext,.ext' entries separated by ';'. Naming a
# tool that already has a hardcoded default replaces that tool's whole set;
# tools left unnamed keep their default. Extensions are case-insensitive and
# the leading dot is optional. Unknown tool names, malformed extensions, or
# the same tool named twice abort startup. Defence in depth against accidents,
# not a security boundary: the check reads the final suffix only.
# TELEGRAM_FILE_EXTENSIONS=send_file:.pdf,.png,.jpg;upload_file:.pdf,.png

# --- File-path tools / allowed roots (optional) ---
# When the MCP client implements Roots but advertises an empty list — or when
# list_roots fails unexpectedly and no client paths can be recovered —
# file-path tools (download_media, send_file, ...) are disabled (deny-all) even
# if server CLI roots are configured. Set this to 1/true to fall back to the
# server CLI roots in those cases. Default is deny-all.
# TELEGRAM_ALLOW_SERVER_ROOTS_FALLBACK=1
# Use the server roots as-is and never send roots/list (for clients that never
# answer it). No effect without server roots. Default is off.
# TELEGRAM_SERVER_ROOTS_ONLY=1

# --- HTTP/SSE transport security (optional) ---
# Only relevant when MCP_TRANSPORT=http or sse. If the server is reachable via
# a domain (e.g. behind a reverse proxy) rather than only 127.0.0.1/localhost,
# set MCP_ALLOWED_HOSTS to enable DNS-rebinding protection and allow that Host
# header. Comma-separated; supports a ":*" suffix to allow any port.
# MCP_ALLOWED_HOSTS=mcp.example.com
# MCP_ALLOWED_ORIGINS=https://mcp.example.com

# --- Proxy (optional) ---
# Route Telegram traffic through a proxy. Set TELEGRAM_PROXY_TYPE to enable.
# Supported types: socks5, socks4, http, mtproxy.
# SOCKS/HTTP proxies require the 'python-socks' package (install via
# `uv sync --extra proxy` or `pip install python-socks`).
# Per-account overrides use the same _<LABEL> suffix as session variables.
# TELEGRAM_PROXY_TYPE=socks5
# TELEGRAM_PROXY_HOST=127.0.0.1
# TELEGRAM_PROXY_PORT=1080
# TELEGRAM_PROXY_USERNAME=<optional>
# TELEGRAM_PROXY_PASSWORD=<optional>
# TELEGRAM_PROXY_RDNS=true
# For MTProxy, set TELEGRAM_PROXY_TYPE=mtproxy and provide the secret:
# TELEGRAM_PROXY_SECRET=<hex secret>
# Per-account override example:
# TELEGRAM_PROXY_TYPE_WORK=http
# TELEGRAM_PROXY_HOST_WORK=proxy.work.example
# TELEGRAM_PROXY_PORT_WORK=3128

# --- Remembered contacts (optional) ---
# TELEGRAM_ALIASES_FILE=/path/to/aliases.json
# TELEGRAM_CONTACT_FUZZY=0   # exact-match aliases only

# --- Voice/video-note transcription (optional) ---
# off: transcribe_voice tool disabled, listings never show transcripts.
# on-demand (default): transcribe_voice works; get_history/get_messages/
#   list_messages fill in already-cached transcripts but never spend an API
#   call fetching a new one during a listing.
# auto: also prefetches missing transcripts during a listing, bounded by
#   TELEGRAM_TRANSCRIBE_MAX_VOICES / _MAX_SECONDS per call.
# TELEGRAM_TRANSCRIBE=on-demand
#
# Which engine transcribe_voice and auto-mode prefetch use by default (the
# per-call engine= argument always overrides this):
# - groq (default): Groq-hosted whisper-large-v3-turbo. Requires GROQ_API_KEY.
#   Downloads the voice note and sends it to Groq - leaves the server, not
#   free, but does not drop the recording's last words the way native
#   Telegram transcription does (proven 2026-08-20, see docs).
# - telegram: native Telegram Premium transcription. Free, audio never
#   leaves Telegram, but empirically drops the last speech segment in
#   roughly 2 of 3 recordings. Requires Telegram Premium on the account.
#   Use for chats that should never be sent to a third party.
# - openai: any OpenAI-compatible /audio/transcriptions endpoint (OpenAI,
#   a self-hosted Parakeet or speaches server, LocalAI, ...), with an
#   optional API key.
# - whisper: local faster-whisper model inside this process. Audio never
#   leaves the machine. Needs: pip install 'telegram-mcp[whisper]'.
# TELEGRAM_TRANSCRIBE_ENGINE=groq
# GROQ_API_KEY=<groq api key, required when engine=groq is ever used>
#
# Language hint (ISO-639-1) for groq/openai/whisper. Unset = auto-detect,
# except on Parakeet servers, which assume English when no language is sent.
# TELEGRAM_TRANSCRIBE_LANGUAGE=nl
# Timeout in seconds for the HTTP engines (groq/openai).
# TELEGRAM_TRANSCRIBE_TIMEOUT=120
#
# engine=openai (base URL, like the OpenAI SDK's base_url; a full
# .../audio/transcriptions URL works too). Parakeet (achetronic/parakeet):
# http://localhost:5092/v1
# TELEGRAM_TRANSCRIBE_OPENAI_URL=https://api.openai.com/v1
# TELEGRAM_TRANSCRIBE_OPENAI_API_KEY=<api key, optional for keyless local servers>
# TELEGRAM_TRANSCRIBE_OPENAI_MODEL=whisper-1
# TELEGRAM_TRANSCRIBE_OPENAI_MAX_MB=25
#
# engine=whisper (faster-whisper model name or local path; loaded once per process)
# TELEGRAM_TRANSCRIBE_WHISPER_MODEL=small
# TELEGRAM_TRANSCRIBE_WHISPER_DEVICE=auto          # auto / cpu / cuda
# TELEGRAM_TRANSCRIBE_WHISPER_COMPUTE_TYPE=default # e.g. int8 on CPU, float16 on GPU
# TELEGRAM_TRANSCRIBE_WHISPER_MODEL_DIR=<where downloaded models are stored>
#
# Per-call budget for TELEGRAM_TRANSCRIBE=auto prefetch (ignored otherwise;
# transcribe_voice itself is never budget-limited since it's an explicit call).
# TELEGRAM_TRANSCRIBE_MAX_VOICES=5
# TELEGRAM_TRANSCRIBE_MAX_SECONDS=300
#
# Where the SQLite transcript cache lives. This is personal-chat text in
# plaintext on disk - keep it on a mounted volume (see docker-compose.yml) and
# in its own directory, not shared with backups of anything else. The file
# gets mode 600; the directory 700.
# TELEGRAM_TRANSCRIPT_CACHE_DIR=data/transcripts