drumsergio/telegram-archive-mcp repository overview

⁠telegram-archive-mcp

An MCP server for any Telegram-Archive⁠ instance. LLMs use it to search messages, browse chats and read archived Telegram history.

⁠Features

• Read-only resources for archive stats, chats, folders and health (telegram-archive://stats, telegram-archive://chats).
• Message search, message paging by offset or keyset cursor, and whole calendar days in a timezone (get_messages_by_date).
• Pinned messages, forum topics and per-chat statistics.
• Signs in to Telegram-Archive through /api/login with TELEGRAM_ARCHIVE_USER and TELEGRAM_ARCHIVE_PASS.
• One JSON-RPC endpoint (/mcp) over HTTP, or stdio with TRANSPORT=stdio.
• Listens on loopback by default; MCP_AUTH_TOKEN adds bearer auth when you expose it.
• Ships as a Docker image, an npm package (npx telegram-archive-mcp) and multi-arch Go binaries.

⁠Quick start

npx telegram-archive-mcp

npx fetches the server and runs it on stdio, so your MCP client starts it for you. For Claude Desktop, Cursor or Claude Code, add:

{
  "mcpServers": {
    "telegram-archive": {
      "command": "npx",
      "args": ["-y", "telegram-archive-mcp"],
      "env": {
        "TELEGRAM_ARCHIVE_URL": "http://localhost:8000",
        "TELEGRAM_ARCHIVE_USER": "admin",
        "TELEGRAM_ARCHIVE_PASS": "your-viewer-password"
      }
    }
  }
}

Set the URL, user and password of your Telegram-Archive viewer. Docker Compose (HTTP on 127.0.0.1:8080) and local builds are in Getting started⁠.

⁠Documentation

The full documentation is at geiserx.github.io/telegram-archive-mcp⁠.

• Getting started⁠: npm, Docker Compose, local build
• Configuration⁠: environment variables and client configuration
• Usage⁠: the 4 resources and 9 tools, paging, reading one day at a time
• Development⁠: testing, contributing, credits
• Related projects⁠: Telegram Archive, other MCP servers, where this one is listed

⁠License

GPL-3.0-or-later⁠