# GeiserX/telegram-archive-mcp [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/GeiserX/telegram-archive-mcp  
**GitHub Stars:** 7  
**npm Downloads (last month):** 1099  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/geiserx-telegram-archive-mcp

## Description
Go-based MCP server for Telegram Archive. Search and browse Telegram chat history, list chats, and retrieve messages with full-text search. Docker image available.

## Tools
Capabilities this server exposes over MCP:

- **list_chats** — Lists 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_folders** — Lists your Telegram folders and their ids.
- **search_all_chats** — Searches message text in every chat at once.
- **search_messages** — Searches one chat, optionally one forum topic.
- **get_messages** — Reads a chat newest first, by offset or keyset cursor, optionally one forum topic.
- **get_message_context** — Returns one message with the messages before and after it.
- **get_messages_by_date** — Returns every message of one calendar day in a timezone.
- **get_pinned_messages** — Returns a chat's pinned messages.
- **get_topics** — Lists a forum group's topics; their ids feed `topic_id`.
- **get_chat_stats** — Message and media counts and size of one chat.
- **get_media** — The photo attached to a message, as an image, or the file's details.
- **refresh_stats** — Makes the viewer recalculate archive-wide statistics. Hidden with `READ_ONLY=1`.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "telegram-archive-mcp": {
    "command": "npx",
    "args": ["-y","telegram-archive-mcp"],
    "env": {
      "TELEGRAM_ARCHIVE_URL": "",
      "TELEGRAM_ARCHIVE_USER": "",
      "TELEGRAM_ARCHIVE_PASS": "",
      "MCP_AUTH_TOKEN": "",
      "READ_ONLY": ""
    }
  }
}
```

**Requires environment variables:** `TELEGRAM_ARCHIVE_URL`, `TELEGRAM_ARCHIVE_USER`, `TELEGRAM_ARCHIVE_PASS`, `MCP_AUTH_TOKEN`, `READ_ONLY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What GeiserX/telegram-archive-mcp does

GeiserX/telegram-archive-mcp gives MCP-compatible clients access to a Telegram-Archive instance. It is designed for reading and searching archived Telegram conversations, not for sending messages or modifying chats. The server exposes structured tool results alongside the same data as JSON text, allowing clients to inspect chat history through their normal MCP interfaces.

The read-oriented toolset supports chat discovery, folder browsing, message search, conversation navigation, forum topics, pinned messages, attached photos, and per-chat statistics. `refresh_stats` is the only tool that changes archive state by asking the viewer to recalculate archive-wide statistics. Setting `READ_ONLY=1` removes that tool.

## How it works

At startup, the server uses `TELEGRAM_ARCHIVE_URL` to reach the viewer and signs in through its `/api/login` endpoint with `TELEGRAM_ARCHIVE_USER` and `TELEGRAM_ARCHIVE_PASS`. MCP clients can launch it as a stdio process, or it can serve requests over Streamable HTTP. The implementation is distributed through npm, Docker, and multi-architecture Go binaries.

A typical workflow starts with `list_chats`, whose returned `ref` values are chat IDs for the other chat-specific tools. `list_folders` and `get_topics` provide folder and forum-topic identifiers. Search can span all chats or target one chat, while `get_messages` supports newest-first reading with offset or keyset-cursor pagination. `get_message_context` centers retrieval around one message, and `get_messages_by_date` reads a calendar day in a chosen timezone.

HTTP binds to loopback by default, validates the request origin, limits request-body size, and requires `MCP_AUTH_TOKEN` when listening on another address. These settings matter when exposing the server beyond the local machine.

## Setup and configuration

For npm-based stdio use, run the `telegram-archive-mcp` package with `npx` and provide the archive URL, viewer username, and viewer password as environment variables. The package obtains the release binary on first start and verifies it against the checksums published with the package. This also supports environments where npm 12 skips install scripts.

Docker can replace the npm command in an MCP client configuration. Use the published `drumsergio/telegram-archive-mcp` image with a release tag rather than the `latest` tag, and pass the same archive connection variables into the container. Long-running HTTP deployments and local builds are also supported.

The documented client configurations cover Claude Code, Claude Desktop, Cursor, VS Code, and Codex. Each launches the server over stdio and supplies the Telegram-Archive URL and credentials.

## Tools and capabilities

- `list_chats` filters chats by name, archive status, or folder and orders them most recently first.
- `search_all_chats` searches message text across the entire archive; `search_messages` limits the search to one chat or forum topic.
- `get_messages`, `get_message_context`, and `get_messages_by_date` support page-oriented, surrounding-context, and date-based reading.
- `list_folders`, `get_topics`, and `get_pinned_messages` expose Telegram organization and pinned content.
- `get_media` returns an attached photo as an image or provides file details; larger images are scaled to 1568 pixels.
- `get_chat_stats` reports message and media counts and storage size, while `refresh_stats` recalculates archive-wide statistics.

## Limitations and notes

The server depends on an accessible Telegram-Archive viewer and valid viewer credentials. Most tools are read-only; `refresh_stats` is the exception unless `READ_ONLY=1` is enabled. HTTP deployments outside loopback require an MCP authentication token. The available archive content and media depend on what the connected Telegram-Archive instance contains.

_Full upstream README: https://allmcps.com/mcp/geiserx-telegram-archive-mcp/readme_