telegram-mcp

Turn Telegram group history into source-linked summaries with Codex or Claude.

What is this?

telegram-mcp is an MCP server and a portable agent skill for summarizing Telegram discussions over exact time ranges. It uses MTProto rather than Bot API, so it can read groups and channels already available to your Telegram account without adding a bot.

Connect it to Codex, Claude, or another MCP client. The client resolves the requested source, reads complete bounded windows, removes overlap, and returns topic and participant summaries with traceable source links.

Related MCP server: Telegram Agent for Codex

Summary-first use cases

One group

Summarize @project_alpha from 30 July 2026 10:00 to 12:00 Europe/Moscow.
Include participant contributions, decisions, risks, resources, and sources.

Several groups

Summarize Project Alpha and Build Room from Monday 09:00 until now.
Keep coverage and sources separate for each group, then show shared topics.

Search and research

• Find a historical message or exact resource link.

• Compare how several communities discussed the same topic.

• Download and inspect referenced media when the user asks for it.

Tools

Full reference with parameters and examples → docs/tools.md

Quick Start

1. Get Telegram API credentials

Go to my.telegram.org, create an app, and grab your API_ID and API_HASH.

2. Install

git clone https://github.com/newink/telegram-mcp.git
cd telegram-mcp
bun install

cp .env.example .env
# Fill in TELEGRAM_API_ID and TELEGRAM_API_HASH

3. Start and authorize via browser

bun start

If no session is configured, the server starts in setup mode and prints an auth URL:

WARN: auth required — open URL to connect Telegram account
      url: "http://localhost:3000/auth?token=a3f9b2c1-..."

Open the URL in your browser — you'll see an auth page where you can sign in with a QR code (scan with Telegram → Settings → Devices → Link Desktop Device) or your phone number. After signing in, the session is saved to .env and the server is ready.

One-time token — the /auth URL is only valid once per server start and expires after successful login. Restarting the server generates a new token.

That's it. Point your MCP client at http://localhost:3000/mcp.

Prefer the terminal? Use bun run auth

bun run auth
# Interactive CLI: QR code or phone number, saves session to .env
bun start

Both flows produce the same result — pick whichever fits your setup.

Docker

Run with Docker Compose — no Bun installation needed:

cp .env.example .env
# Fill in TELEGRAM_API_ID and TELEGRAM_API_HASH

docker compose up

The first time you start the container without a TELEGRAM_SESSION, it will print an auth URL — open it in your browser to sign in. The session is persisted to ./bot-data/ so you only need to auth once.

docker build -t telegram-mcp .

docker run -p 3000:3000 \
  --env-file .env \
  -e ENV_FILE=/app/bot-data/.env \
  -v ./bot-data:/app/bot-data \
  telegram-mcp

Pull pre-built image

# Latest stable
docker pull newink/telegram-mcp

# Or from GitHub Container Registry
docker pull ghcr.io/newink/telegram-mcp

Supported platforms: linux/amd64, linux/arm64 (Raspberry Pi, Apple Silicon via Rosetta).

How the summary agent works

1. Normalize the inclusive start, end, and timezone.

2. Resolve each group or channel without guessing ambiguous names.

3. Read up to 500 messages per bounded request without marking them as read.

4. Split saturated intervals into smaller overlapping windows.

5. Verify coverage and stop safely on Telegram access errors.

6. Deduplicate overlaps and sort messages chronologically.

7. Cluster substantive topics and attribute each claim to participants.

8. Cite public Telegram messages and preserve external URLs exactly.

9. Separate facts from conclusions and disclose partial reads or uninspected attachments.

The packaged skill is .agents/skills/telegram-summary/SKILL.md. It is read-only: summary requests never invoke Telegram write tools.

Representative result:

### Runtime upgrade
- Anna (@anna) proposed the upgrade after mock CI.
- Boris (@boris) identified a container compatibility risk and requested a smoke test.
- Decision: run both checks before reconsidering the upgrade.
- Sources: https://t.me/project_alpha/5101, https://t.me/project_alpha/5102

Private groups receive message IDs instead of fabricated public links. Media contents are excluded unless the attachment was explicitly downloaded and inspected.

Connect to Your AI Client

Codex

This repository includes .codex/config.toml:

[mcp_servers.telegram]
url = "http://localhost:3000/mcp"

Start the MCP server, open the repository in Codex, and ask for a date-and-source summary. The packaged skill provides the orchestration contract.

Claude Desktop

Start the server first (bun start), then add to claude_desktop_config.json:

{
  "mcpServers": {
    "telegram": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

mcporter / OpenClaw

{
  "mcpServers": {
    "telegram": {
      "baseUrl": "http://localhost:3000/mcp"
    }
  }
}

Direct HTTP (any client)

# Initialize session first, then call tools:
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_dialogs","arguments":{"query":"news"}}}'

Environment Variables

*Not required when TELEGRAM_MOCK=true.

Development

bun dev              # Start with hot reload
bun test             # Run tests (uses mock automatically)
bun run typecheck    # TypeScript check
bun run lint         # Biome lint + format
bun run lint:fix     # Auto-fix lint issues
bun run knip         # Find dead code
bun run audit        # Dead code, docs, env coverage, and TODO checks

Mock mode — develop and test without a real Telegram account:

TELEGRAM_MOCK=true bun dev   # server with fake data
TELEGRAM_MOCK=true bun test  # run tests

Mock data includes sample dialogs, messages, and media — enough to build and test new tools without touching the real API.

Project structure and architecture → docs/architecture.md MTProto specifics and gotchas → docs/mtproto.md Adding new tools → docs/tools.md Testing and BDD scenarios → docs/testing.md

Built With

• Bun — runtime & package manager

• mtcute — MTProto client for TypeScript

• @modelcontextprotocol/sdk — MCP server SDK

• Zod — schema validation

• Biome — linter & formatter

License

MIT