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

• Speaks MCP 2026-07-28 and every earlier revision down to 2024-11-05 on stdio and Streamable HTTP. Clients that still use the initialize handshake work unchanged.
• Search one chat or every chat at once, read a chat page by page, one calendar day in your timezone, or the conversation around one message.
• Forum topics, pinned messages, folders 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).
• Every tool is read-only except refresh_stats; READ_ONLY=1 hides that one too.
• Signs in to Telegram-Archive through /api/login with TELEGRAM_ARCHIVE_USER and TELEGRAM_ARCHIVE_PASS.
• HTTP listens on loopback by default, checks Origin, caps request bodies, and requires MCP_AUTH_TOKEN on any other address.
• Ships as an npm package, a Docker image and multi-arch Go binaries.

⁠Install

Every client below runs the server over stdio. Set the URL, user and password of your Telegram-Archive viewer.

Claude Code

claude mcp add --env TELEGRAM_ARCHIVE_URL=http://localhost:8000 \
  --env TELEGRAM_ARCHIVE_USER=admin --env TELEGRAM_ARCHIVE_PASS=your-viewer-password \
  --transport stdio telegram-archive -- npx -y telegram-archive-mcp

Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json)

{
  "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"
      }
    }
  }
}

VS Code (.vscode/mcp.json, asks for the password once)

{
  "inputs": [
    { "type": "promptString", "id": "tg-pass", "description": "Telegram-Archive viewer password", "password": true }
  ],
  "servers": {
    "telegram-archive": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "telegram-archive-mcp"],
      "env": {
        "TELEGRAM_ARCHIVE_URL": "http://localhost:8000",
        "TELEGRAM_ARCHIVE_USER": "admin",
        "TELEGRAM_ARCHIVE_PASS": "${input:tg-pass}"
      }
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.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" }

Docker, for any client above: use docker as the command with these arguments, and a release tag from the releases page⁠, never latest:

docker run -i --rm -e TELEGRAM_ARCHIVE_URL -e TELEGRAM_ARCHIVE_USER -e TELEGRAM_ARCHIVE_PASS drumsergio/telegram-archive-mcp:vX.Y.Z

The npm package downloads the release binary on first start and checks it against the checksums published with the package, so it also works with npm 12, which skips install scripts. A long-running HTTP server (Docker Compose) and local builds are in Getting started⁠.

⁠Tools

Every tool returns structured content with an output schema, alongside the same JSON as text. Arguments and defaults are on Usage⁠.

⁠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 12 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⁠