tg-mcp

Read-only Telegram digest MCP server for selected Telegram chats and channels.

Current shape

• Node.js 22 ESM service.
• Express + MCP Streamable HTTP endpoint at /mcp.
• REST/OpenAPI fallback under /tg-mcp/api and /tg-mcp/openapi.json.
• MongoDB storage.
• GramJS-based Telegram sync CLI.
• Optional read-only Telegram slash bot.
• Read-only MCP tools:
  • list_sources
  • get_sync_status
  • get_daily_digest
  • get_period_summary
  • search_telegram_messages
  • get_message_context
  • get_action_items
  • get_source_summary

Local development

npm ci
npm run cli -- setup-env
npm test
npm start

Health:

curl http://127.0.0.1:3010/health

REST/OpenAPI fallback:

curl http://127.0.0.1:3010/tg-mcp/openapi.json
curl "http://127.0.0.1:3010/tg-mcp/api/sync/status"
curl "http://127.0.0.1:3010/tg-mcp/api/digest/daily?timelineLimit=80"
curl "http://127.0.0.1:3010/tg-mcp/api/sources/<sourceId>/summary?date=2026-07-09"
curl "http://127.0.0.1:3010/tg-mcp/api/digest/daily?sourceQuery=project"
curl "http://127.0.0.1:3010/tg-mcp/api/digest/daily?refresh=true"
curl "http://127.0.0.1:3010/tg-mcp/api/search?query=release"

If APP_AUTH_TOKEN is set, pass Authorization: Bearer <token> for REST and MCP calls.

Telegram setup

Fill these values in .env or /srv/tg-mcp/shared/.env:

TELEGRAM_API_ID=
TELEGRAM_API_HASH=
TELEGRAM_SESSION_FILE=/srv/tg-mcp/shared/sessions/telegram.session
ALLOWED_SOURCE_IDS=

Create or update the env file:

npm run cli -- setup-env --set TELEGRAM_API_ID=<api_id> --set TELEGRAM_API_HASH=<api_hash>

For the VPS layout:

export TELEGRAM_API_ID=<api_id>
export TELEGRAM_API_HASH=<api_hash>
npm run cli -- setup-env --production --env-path /srv/tg-mcp/shared/.env --from-env TELEGRAM_API_ID --from-env TELEGRAM_API_HASH

Existing secrets are preserved unless you pass a new value with --set or --from-env. The command writes mode 0600, creates a backup before overwriting an existing file, and generates APP_AUTH_TOKEN when it is missing.

List available sources:

npm run cli -- login
npm run cli -- doctor --telegram
npm run cli -- list-sources

Save the source list into MongoDB, then enable selected chats/channels:

npm run cli -- refresh-sources
npm run cli -- find-sources project
npm run cli -- select-source "Project Alpha" --tag work
npm run cli -- sync

Useful variants:

npm run cli -- disable-source <id>
npm run cli -- set-source-tags <id> --tag work --tag project-x
npm run cli -- enable-source <id> --tag work
npm run cli -- db-sources --include-disabled
npm run cli -- sync --source-id <id> --limit 100
npm run cli -- backfill --days 7 --limit 1000

Alternatively, put selected source ids into ALLOWED_SOURCE_IDS; env selection overrides DB-enabled sources during sync.

login is interactive and writes the Telegram session file. Later commands reuse that session and should not prompt unless Telegram requires reauthorization.

Check readiness:

npm run cli -- doctor
npm run cli -- doctor --telegram

doctor returns machine-readable checks plus nextSteps with the next safe commands for the current setup state. doctor --telegram also performs a non-interactive authorization check with the existing session file.

Admin operations

Authenticated admin endpoints are available for operations that should not be exposed as MCP tools:

curl -X POST http://127.0.0.1:3010/admin/sync \
  -H "Authorization: Bearer <APP_AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"sourceIds":["<sourceId>"],"limit":100}'

Use {"backfillDays":7} to bypass the incremental cursor for a historical import. The endpoint uses the existing Telegram session file and never prompts.

Background sync

The HTTP service can run a safe background sync loop after the Telegram session file exists:

TELEGRAM_SYNC_ENABLED=true
TELEGRAM_SYNC_INTERVAL_SECONDS=300
TELEGRAM_SYNC_ON_START=true

If credentials, session, or selected sources are missing, the worker logs a warning and waits for the next interval. It never prompts from the systemd service.

Normal sync is incremental: each source tracks lastSyncedMessageId and later runs request only newer Telegram messages. backfill --days N intentionally bypasses that cursor for historical imports.

Check data freshness:

curl "http://127.0.0.1:3010/tg-mcp/api/sync/status?staleAfterHours=24"

The MCP tool get_sync_status exposes the same source freshness state to ChatGPT so it can say when data is missing or stale before summarizing.

Digest cache

Daily, period, and source summaries are cached in tg_digests. The cache key includes the period, timezone, source filters, timeline options, and selected source sync state, so a later Telegram sync naturally invalidates stale summaries.

Use refresh=true in REST calls, or refresh: true in MCP tool arguments, to force recomputation from stored messages.

Optional Telegram slash bot

The HTTP service can also run a small read-only Telegram bot for quick checks against the same selected data:

TELEGRAM_BOT_ENABLED=true
TELEGRAM_BOT_TOKEN=<bot token from BotFather>
TELEGRAM_BOT_ALLOWED_CHAT_IDS=<your chat id or comma-separated ids>
TELEGRAM_BOT_TIMEZONE=Europe/Chisinau

Supported commands:

/digest_today [source]
/digest_week [source]
/search <query>
/actions [source]
/sources [query]

TELEGRAM_BOT_ALLOWED_CHAT_IDS is optional, but recommended. The bot never sends Telegram messages on behalf of the synced user account; it only replies with digests/search results from MongoDB.

VPS quick deploy

The target server already has Apache, MongoDB, and bundled Node.js.

Expected layout:

/srv/tg-mcp/
  repo.git/
  releases/
  shared/
    .env
    logs/
    sessions/
    node/
  current -> releases/<release>

Deploy code:

ops/deploy.sh

Install systemd service:

sudo ops/install-systemd-service.sh

Install Apache /mcp proxy:

sudo ops/install-apache-proxy.sh

Install log rotation for /srv/tg-mcp/shared/logs/*.log:

sudo ops/install-logrotate.sh

That installer exposes:

https://celticspear.com/mcp
https://celticspear.com/tg-mcp/openapi.json
https://celticspear.com/tg-mcp/api/...