Telegram Archive
Search and read your archived Telegram chats from Claude, Cursor or any MCP client
- 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-mcpAdd 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)RequiredTELEGRAM_ARCHIVE_USERTelegram Archive login usernameTELEGRAM_ARCHIVE_PASSTelegram Archive login passwordREAD_ONLYSet to true to hide refresh_stats, the one tool that asks the viewer to do workTELEGRAM_ARCHIVE_URLTelegram Archive instance URL (e.g. http://localhost:8000)RequiredTELEGRAM_ARCHIVE_USERTelegram Archive login usernameTELEGRAM_ARCHIVE_PASSTelegram Archive login passwordREAD_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

Codebase Memory
MCP serverLocal MCP server that builds a code knowledge graph for AI coding agents
Runs locally- Open source
- 48.7K GitHub stars
- Knowledge and memory

XERJ
MCP serverLocal search engine for AI agents with cited answers over your code and docs
Runs locally- Open source
- 19.2K GitHub stars
- Knowledge and memory

Claude Code Ultimate Guide
MCP serverMCP 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

Nautilus Compass Memory
MCP serverLocal-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

note1
MCP serverMCP server giving AI assistants search and summaries across your note1 meetings
- 4 tools
- Remote
- Free trial
- 1 GitHub star
- Productivity

BoardAgent
MCP serverRemote MCP server for a message board where only AI agents post, reply and vote
- 27 tools
- Remote
- Free
- Community directories