# Telegram Archive

> Telegram Archive is an open-source MCP server for communication. Search and read your archived Telegram chats from Claude, Cursor or any MCP client. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, API
- **Website:** https://geiserx.github.io/telegram-archive-mcp/
- **Repository:** https://github.com/geiserx/telegram-archive-mcp
- **MCP Registry name:** io.github.GeiserX/telegram-archive-mcp
- **Categories:** communication, knowledge and memory
- **Listing updated:** 2026-11-14

## About

It sits in front of a Telegram Archive viewer, not Telegram itself. The server signs in to the viewer's HTTP API with the viewer's own login, keeps the session cookie in memory and reads whatever the backup has already saved. Messages the backup has not fetched yet are not there.

The assistant can find a chat, search it by keyword, read the messages around a hit, or pull every message from one calendar day in your timezone. It can also page through a long chat newest first, narrow results to a forum topic and look at the photo attached to a message. The photo is scaled to 1568 pixels if larger; other files return only their name, type and size.

Every tool is read-only except refresh_stats, which asks the viewer to recalculate statistics; setting READ_ONLY=1 hides it. It stores nothing of its own, no database and no cache. Over HTTP it listens on loopback by default and requires MCP_AUTH_TOKEN for any other address.

## Features

- **Search across all chats:** One keyword search covers every archived chat, or a single chat and optionally a single forum topic.
- **Read by day:** Returns every message of one calendar day in your timezone, or pages through a chat newest first.
- **Message context:** Shows the messages before and after a hit so the assistant can read the surrounding conversation.
- **Photo viewing:** Returns a message's photo as an image the model can look at, scaled to 1568 pixels when larger.
- **Read-only by design:** Only refresh_stats asks the viewer to do work, and READ_ONLY=1 hides it.
- **Several ways to run:** Ships as an npm package, a Docker image and Go binaries for Linux, macOS and Windows.

## Good for

- Find an address someone posted in a group months ago
- Reconstruct what was said in a chat on one particular day
- Summarise a long forum-style group by topic
- List which chats sit in a Telegram folder
- Check pinned messages in a chat without opening the viewer

## Install

### Claude Code (Terminal)

```sh
claude mcp add telegram-archive-mcp --env TELEGRAM_ARCHIVE_URL='<TELEGRAM_ARCHIVE_URL>' --env TELEGRAM_ARCHIVE_PASS='<TELEGRAM_ARCHIVE_PASS>' -- npx -y telegram-archive-mcp
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "telegram-archive-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "telegram-archive-mcp"
      ],
      "env": {
        "TELEGRAM_ARCHIVE_URL": "<TELEGRAM_ARCHIVE_URL>",
        "TELEGRAM_ARCHIVE_PASS": "<TELEGRAM_ARCHIVE_PASS>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `list_chats`: Lists chats, most recent first, filtered by name, archived state or folder.
- `list_folders`: Lists 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 cursor.
- `get_message_context`: Returns one message with the messages around it.
- `get_messages_by_date`: Returns every message of one calendar day in your timezone.
- `get_media`: Returns a message's photo as an image, or name, type and size of other files.
- `refresh_stats`: Asks the viewer to recalculate statistics; hidden by READ_ONLY=1.

## FAQ

### Does it connect to Telegram directly?

No. It only reads from a Telegram Archive viewer that already holds your backup.

### Can it send or delete messages?

No. It never sends, edits or deletes messages in Telegram or in the archive.

### What settings does it need?

TELEGRAM_ARCHIVE_URL is required; TELEGRAM_ARCHIVE_USER and TELEGRAM_ARCHIVE_PASS are the viewer login.

### Which clients can use it?

The README shows setup for Claude Code, Claude Desktop, Cursor, VS Code and Codex over stdio, plus an HTTP mode.

### Is Telegram Archive free?

Yes. Telegram Archive is open source, so you can use and self-host it for free.

### How do I add Telegram Archive to Claude Code?

Run this command in your terminal: claude mcp add telegram-archive-mcp --env TELEGRAM_ARCHIVE_URL='<TELEGRAM_ARCHIVE_URL>' --env TELEGRAM_ARCHIVE_PASS='<TELEGRAM_ARCHIVE_PASS>' -- npx -y telegram-archive-mcp

### What are the best alternatives to Telegram Archive?

The closest alternatives to Telegram Archive are Codebase Memory, XERJ, Claude Code Ultimate Guide, Nautilus Compass Memory and note1.

## Alternatives

- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.
- [BoardAgent](https://ai-powered.com/mcp/boardagent): BoardAgent is a free MCP server for community directories.
- [Callout](https://ai-powered.com/mcp/callout): Callout is a freemium MCP server for communication.
- [MedXpert 图书馆连接器（通用版）](https://ai-powered.com/mcp/medxpert): MedXpert 图书馆连接器（通用版） is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/telegram-archive
