English Français العربية

Telegram Archive

Official registry Search and web

Search and read your archived Telegram chats and messages

Source code Website Documentation

What can you do with Telegram Archive?

  • 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.

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package telegram-archive-mcp
Claude Code 
claude mcp add telegram-archive -e 'TELEGRAM_ARCHIVE_URL=<TELEGRAM_ARCHIVE_URL>' -e 'TELEGRAM_ARCHIVE_USER=<TELEGRAM_ARCHIVE_USER>' -e 'TELEGRAM_ARCHIVE_PASS=<your telegram_archive_pass>' -e 'READ_ONLY=<READ_ONLY>' -- npx -y telegram-archive-mcp@0.4.0
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "telegram-archive": {
            "command": "npx",
            "args": [
                "-y",
                "telegram-archive-mcp@0.4.0"
            ],
            "env": {
                "TELEGRAM_ARCHIVE_URL": "<TELEGRAM_ARCHIVE_URL>",
                "TELEGRAM_ARCHIVE_USER": "<TELEGRAM_ARCHIVE_USER>",
                "TELEGRAM_ARCHIVE_PASS": "<your telegram_archive_pass>",
                "READ_ONLY": "<READ_ONLY>"
            }
        }
    }
}

Environment variables

  • TELEGRAM_ARCHIVE_URL required Telegram Archive instance URL (e.g. http://localhost:8000)
  • TELEGRAM_ARCHIVE_USER Telegram Archive login username
  • TELEGRAM_ARCHIVE_PASS secret Telegram Archive login password
  • READ_ONLY Set to true to hide refresh_stats, the one tool that asks the viewer to do work
OCI package drumsergio/telegram-archive-mcp:v0.4.0
Claude Code 
claude mcp add telegram-archive -e 'TELEGRAM_ARCHIVE_URL=<TELEGRAM_ARCHIVE_URL>' -e 'TELEGRAM_ARCHIVE_USER=<TELEGRAM_ARCHIVE_USER>' -e 'TELEGRAM_ARCHIVE_PASS=<your telegram_archive_pass>' -e 'READ_ONLY=<READ_ONLY>' -- docker run -i --rm drumsergio/telegram-archive-mcp:v0.4.0
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "telegram-archive": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "drumsergio/telegram-archive-mcp:v0.4.0"
            ],
            "env": {
                "TELEGRAM_ARCHIVE_URL": "<TELEGRAM_ARCHIVE_URL>",
                "TELEGRAM_ARCHIVE_USER": "<TELEGRAM_ARCHIVE_USER>",
                "TELEGRAM_ARCHIVE_PASS": "<your telegram_archive_pass>",
                "READ_ONLY": "<READ_ONLY>"
            }
        }
    }
}

Environment variables

  • TELEGRAM_ARCHIVE_URL required Telegram Archive instance URL (e.g. http://localhost:8000)
  • TELEGRAM_ARCHIVE_USER Telegram Archive login username
  • TELEGRAM_ARCHIVE_PASS secret Telegram Archive login password
  • READ_ONLY Set to true to hide refresh_stats, the one tool that asks the viewer to do work

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. telegram-archive-mcp
  2. Features
  3. Quick start
  4. Documentation
  5. License

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

Frequently asked questions

What is Telegram Archive?

Search and read your archived Telegram chats and messages

How do I install Telegram Archive?

It runs on your machine. In Claude Code: claude mcp add telegram-archive -e 'TELEGRAM_ARCHIVE_URL=<TELEGRAM_ARCHIVE_URL>' -e 'TELEGRAM_ARCHIVE_USER=<TELEGRAM_ARCHIVE_USER>' -e 'TELEGRAM_ARCHIVE_PASS=<your telegram_archive_pass>' -e 'READ_ONLY=<READ_ONLY>' -- npx -y telegram-archive-mcp@0.4.0. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Telegram Archive need an API key?

Yes. It expects TELEGRAM_ARCHIVE_URL, TELEGRAM_ARCHIVE_PASS, which you set in its configuration.

Is Telegram Archive open source?

Yes. Its code is on GitHub under the GPL-3.0 license.

Who maintains Telegram Archive?

It is published by GeiserX. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.