Telegram Digest MCP Server

Standalone Go MCP server that connects to Telegram MTProto and exposes tools for digest workflows.

Contents

• main.go - MCP server + Telegram client
• auth.go - OAuth/OIDC middleware and metadata/proxy endpoints
• logging.go - log level helpers (MCP_LOG_LEVEL=info|debug)
• auth_test.go - auth middleware tests
• Makefile - build/run/test/tunnel helpers
• Dockerfile - multi-stage Linux container build
• docker-compose.yml - local Docker Compose template

Prerequisites

• Go 1.23+
• Telegram API credentials (api_id, api_hash) from https://my.telegram.org/apps
• cloudflared (optional, for temporary public tunnel)
• Docker + Compose plugin (optional, for containerized runs)

Quick Start

cp .env.example .env
# edit .env with your real values

make tidy
make build
make run

First interactive run may ask for Telegram auth code.

Docker (Recommended For Deployments)

cp .env.example .env
# edit .env with real values

docker compose build

First run should be interactive once to complete Telegram login and persist session:

make docker-auth

After successful login, start normally:

make docker-up
make docker-logs

Notes:

• Compose stores Telegram session data in Docker volume telegram_mcp_data.
• Container sets SESSION_DIR=/data, so gotd session is persisted across restarts.
• docker-compose.yml binds to 127.0.0.1:8765 by default for local-only exposure.
• For reverse proxy only, remove ports and attach the service to your proxy network.

Quick MCP Check (No Auth)

Start server in no-auth mode:

make docker-up-noauth

Check MCP connectivity with FastMCP:

fastmcp list http://127.0.0.1:8765/mcp

Expected result: FastMCP prints the available tools (3 tools in this server).

Make Commands

make tidy        # go mod tidy
make test        # go test ./...
make build       # go build -o telegram-digest-mcp .
make run         # run with current env
make run-debug   # run with MCP_LOG_LEVEL=debug
make run-noauth  # run with MCP_AUTH_MODE=off (local testing only)
make tunnel      # cloudflared temporary tunnel to http://localhost:${PORT}
make docker-up   # docker compose up -d --build
make docker-up-noauth # docker compose up -d --build with MCP_AUTH_MODE=off
make docker-down # docker compose down
make docker-logs # follow container logs
make docker-auth # interactive first run for Telegram OTP/2FA

Defaults:

• BIN_NAME=telegram-digest-mcp
• PORT=8765

Override example:

make PORT=9000 tunnel

OAuth/OIDC

Secure mode is default:

• MCP_AUTH_MODE=oauth
• MCP_OAUTH_ISSUER=https://<tenant>.auth0.com/
• MCP_OAUTH_AUDIENCE=https://<your-public-host>/mcp (must exactly match Auth0 API Identifier)
• MCP_OAUTH_REQUIRED_SCOPES=mcp.read
• MCP_PUBLIC_BASE_URL=https://<public-host>

Detailed Auth0 setup guide: AUTH0_MCP_CONFIGURATION.md

The server exposes:

• GET /.well-known/oauth-protected-resource
• GET /.well-known/oauth-authorization-server
• GET /authorize (proxy)
• POST /token (proxy)

MCP Tools

This server exposes 3 MCP tools:

1. get_messages(channels, hours_back=24) Fetches recent posts from one or more public Telegram channels and returns text, timestamp, views, forwards, and message links.

2. get_similar_channels(channels) Uses Telegram recommendations to find adjacent/similar channels for the provided seeds.

3. expand_and_collect(seed_channels, depth=2, hours_back=24) Runs a full pipeline: expands from seed channels into nearby channels, then collects recent posts from the full discovered set.

Why this is useful for social-media bubble analysis:

• You can start from a known channel and map nearby communities automatically.
• You can compare narratives across adjacent bubbles instead of looking at one channel in isolation.
• You can feed structured, cross-channel data to AI for clustering, summarization, trend detection, and narrative drift analysis over time.

Security Notes

• Keep .env and Telegram session files private.
• Do not run with MCP_AUTH_MODE=off on public internet.
• Logs go to stderr (MCP protocol uses stdout).