<div align="center">

telegram-mcp

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

</div>

---

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.

---

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

Tool	Description
search_dialogs	Search chats, groups, and channels by name or username
get_messages	Fetch messages with date range, unread filter, and mark-as-read support
search_messages	Full-text search across all chats or within a specific chat
media_download	Download media (photo, video, document) from a message to a local file
message_from_link	Fetch a message by its t.me/... link
delete_messages	Delete messages from a chat (requires opt-in via bot-data/config.yml)
send_message	Send a text message to a chat (requires opt-in via bot-data/config.yml)
send_file	Send a local file to a chat as a document (requires opt-in via bot-data/config.yml)

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.

<details> <summary>Manual docker run</summary>

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

</details>

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/meeting-minutes/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

Variable	Required	Description
TELEGRAM_API_ID	Yes*	From my.telegram.org
TELEGRAM_API_HASH	Yes*	From my.telegram.org
TELEGRAM_SESSION	Yes*	Generated by browser auth or bun run auth
PORT	No	Server port (default: 3000)
LOG_LEVEL	No	Pino log level: trace|debug|info|warn|error (default: info)
TELEGRAM_MOCK	No	Set true to use mock data (no real Telegram needed)
TELEGRAM_MCP_CONFIG	No	Write-tool allowlist path (default: bot-data/config.yml)
KEEPALIVE_INTERVAL_MS	No	Session keepalive interval (default: 6 hours)

*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