GeiserX/telegram-archive-mcp

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.
• The photo attached to a message, returned as an image the model can look at and scaled to 1568 pixels when larger (get_media).
• 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 10 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