Skip to content
MCP server

Telegram Archive

Search and read your archived Telegram chats from Claude, Cursor or any MCP client

Runs locallyStatus and history
Pricing
Open source
Platforms
CLI, self-hosted, API
Runs
Locally
Version
0.4.2
Listing updated
3 days ago

About Telegram Archive

Telegram Archive is an open-source MCP server for communication. It runs locally on your machine and is started by your AI client.

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.

Install

Run in a 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

Add to claude_desktop_config.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>"
      }
    }
  }
}

Add to ~/.cursor/mcp.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>"
      }
    }
  }
}

Add to .vscode/mcp.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>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.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>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

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

Configuration

  • TELEGRAM_ARCHIVE_URLTelegram Archive instance URL (e.g. http://localhost:8000)Required
  • TELEGRAM_ARCHIVE_USERTelegram Archive login username
  • TELEGRAM_ARCHIVE_PASSTelegram Archive login password
  • READ_ONLYSet to true to hide refresh_stats, the one tool that asks the viewer to do work
  • TELEGRAM_ARCHIVE_URLTelegram Archive instance URL (e.g. http://localhost:8000)Required
  • TELEGRAM_ARCHIVE_USERTelegram Archive login username
  • TELEGRAM_ARCHIVE_PASSTelegram Archive login password
  • READ_ONLYSet to true to hide refresh_stats, the one tool that asks the viewer to do work

Tools this server provides (9)

Taken from the project documentation; the running server may differ.

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.

What it does

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

Pricing

Open source

Free to run; requires your own Telegram Archive instance

Prices change. Check geiserx.github.io before you buy.

Telegram Archive 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 to Telegram Archive

  1. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  2. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  3. MCP server for searching the Claude Code Ultimate Guide from any MCP client

    Runs locally
    • Open source
    • 6.5K GitHub stars
    • AI models and LLM tooling
  4. Local-first long-term memory layer for AI agents, served over MCP

    Not checked yet
    • 5 tools
    • Remote
    • Open source
    • 1.3K GitHub stars
    • Knowledge and memory
  5. note1

    MCP server

    MCP server giving AI assistants search and summaries across your note1 meetings

    • 4 tools
    • Remote
    • Free trial
    • 1 GitHub star
    • Productivity
  6. BoardAgent

    MCP server

    Remote MCP server for a message board where only AI agents post, reply and vote

    • 27 tools
    • Remote
    • Free
    • Community directories