Telegram Archive

io.github.GeiserXPublished by GitHub account GeiserXv0.4.1Updated Oct 29, 2026

Search and read your archived Telegram chats and messages

VerifiedSTDIODesktop onlyKnowledge & MemoryCommunication & Collaboration

Overview

AI-generated overview

MCP server that lets an assistant search, browse and read the Telegram chats archived in a self-hosted Telegram-Archive instance.

What you can do
  • List chats and folders, with filters by name, archived state or folder
  • Search message text across all chats or within one chat or forum topic
  • Read a chat page by page, a single calendar day in a timezone, or the messages around one message
  • List forum topics, pinned messages and per-chat message and media statistics
  • Return the photo attached to a message as an image the model can view
When to use it
Useful when you already run a Telegram-Archive viewer and want an assistant to look things up in your saved Telegram history: finding past messages, summarizing a chat or a day, or reading context around a specific message.
Requirements
Runs locally over stdio via npx or Docker. Needs a reachable Telegram-Archive instance URL (TELEGRAM_ARCHIVE_URL) plus viewer login credentials in TELEGRAM_ARCHIVE_USER and TELEGRAM_ARCHIVE_PASS. The npm package downloads a release binary on first start and verifies it against published checksums.
Before you install
The server signs in to your archive with the viewer username and password, so store TELEGRAM_ARCHIVE_PASS as a secret rather than in plain config. All tools are read-only except refresh_stats, which makes the viewer recalculate archive-wide statistics; set READ_ONLY to hide it. Message content and media from your archive are passed to the model.

Installation

In SourceWeft

  1. Open Telegram Archive in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[telegram-archive-mcp]

telegram-archive-mcp

[npm] [CI] [License] [Docker Pulls] [codecov]

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

sh
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)

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)

json
{  "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)

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:

sh
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

ToolWhat it does
list_chatsLists chats, most recent first; filter by search (name), archived or folder_id. Each chat's ref is the chat_id the other tools take.
list_foldersLists your Telegram folders and their ids.
search_all_chatsSearches message text in every chat at once.
search_messagesSearches one chat, optionally one forum topic.
get_messagesReads a chat newest first, by offset or keyset cursor, optionally one forum topic.
get_message_contextReturns one message with the messages before and after it.
get_messages_by_dateReturns every message of one calendar day in a timezone.
get_pinned_messagesReturns a chat's pinned messages.
get_topicsLists a forum group's topics; their ids feed topic_id.
get_chat_statsMessage and media counts and size of one chat.
get_mediaThe photo attached to a message, as an image, or the file's details.
refresh_statsMakes the viewer recalculate archive-wide statistics. Hidden with READ_ONLY=1.

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

Source: README.md at commit 2a8f863

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

5
  1. v0.4.1LatestOct 29, 2026
  2. v0.3.1Oct 21, 2026
  3. v0.3.0Oct 16, 2026
  4. v0.1.3Oct 5, 2026
  5. v0.0.2Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts