telegram-archive-mcp — Claude Code MCP server: setup and overview
Connects language models to a Telegram-Archive deployment to search message history, inspect forum topics, and retrieve attached pictures.
claude mcp add --env TELEGRAM_ARCHIVE_URL=<TELEGRAM_ARCHIVE_URL> --env TELEGRAM_ARCHIVE_USER=<TELEGRAM_ARCHIVE_USER> --env TELEGRAM_ARCHIVE_PASS=<TELEGRAM_ARCHIVE_PASS> --transport stdio telegram-archive-mcp -- npx -y telegram-archive-mcpWhat telegram-archive-mcp does
The server links your assistant to a self-hosted Telegram-Archive instance through its /api/login endpoint. It exposes read-only data resources such as telegram-archive://stats and telegram-archive://chats, letting models inspect folders, chat metadata, and health state without modifying any records.
Querying tools handle cursor-based message paging, pinned entries, forum topics, and day-by-day extractions via get_messages_by_date with timezone offsets. When entries contain photos, the get_media tool serves them directly to multimodal models, downscaling images wider than 1568 pixels.
You need an active Telegram-Archive viewer running beforehand, as the server cannot work without a valid TELEGRAM_ARCHIVE_URL and login credentials.
What it helps with
- query past Telegram discussions across archived channels
- fetch chat logs for a selected calendar date and timezone
- retrieve resized image attachments for multimodal analysis
- inspect forum topics and pinned messages inside archived groups
Example prompts for the agent
- Check telegram-archive://chats and list all available discussion groups
- Collect chat entries from yesterday using get_messages_by_date for UTC
- Retrieve the photo attached to message 105 via get_media and explain what is depicted
How to install telegram-archive-mcp
Platform CLI
claude mcp add --env TELEGRAM_ARCHIVE_URL=<TELEGRAM_ARCHIVE_URL> --env TELEGRAM_ARCHIVE_USER=<TELEGRAM_ARCHIVE_USER> --env TELEGRAM_ARCHIVE_PASS=<TELEGRAM_ARCHIVE_PASS> --transport stdio telegram-archive-mcp -- npx -y telegram-archive-mcpReplace <…> with your own values
Platform CLI
codex mcp add telegram-archive-mcp --env TELEGRAM_ARCHIVE_URL=<TELEGRAM_ARCHIVE_URL> --env TELEGRAM_ARCHIVE_USER=<TELEGRAM_ARCHIVE_USER> --env TELEGRAM_ARCHIVE_PASS=<TELEGRAM_ARCHIVE_PASS> -- npx -y telegram-archive-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"telegram-archive-mcp": {
"command": "npx",
"args": [
"-y",
"telegram-archive-mcp"
],
"env": {
"TELEGRAM_ARCHIVE_URL": "<TELEGRAM_ARCHIVE_URL>",
"TELEGRAM_ARCHIVE_USER": "<TELEGRAM_ARCHIVE_USER>",
"TELEGRAM_ARCHIVE_PASS": "<TELEGRAM_ARCHIVE_PASS>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"telegram-archive-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"telegram-archive-mcp"
],
"env": {
"TELEGRAM_ARCHIVE_URL": "<TELEGRAM_ARCHIVE_URL>",
"TELEGRAM_ARCHIVE_USER": "<TELEGRAM_ARCHIVE_USER>",
"TELEGRAM_ARCHIVE_PASS": "<TELEGRAM_ARCHIVE_PASS>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e TELEGRAM_ARCHIVE_URL=<TELEGRAM_ARCHIVE_URL> -e TELEGRAM_ARCHIVE_USER=<TELEGRAM_ARCHIVE_USER> -e TELEGRAM_ARCHIVE_PASS=<TELEGRAM_ARCHIVE_PASS> telegram-archive-mcp npx -y telegram-archive-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about telegram-archive-mcp
How do I install telegram-archive-mcp in Claude Code?
Run `claude mcp add --env TELEGRAM_ARCHIVE_URL=<TELEGRAM_ARCHIVE_URL> --env TELEGRAM_ARCHIVE_USER=<TELEGRAM_ARCHIVE_USER> --env TELEGRAM_ARCHIVE_PASS=<TELEGRAM_ARCHIVE_PASS> --transport stdio telegram-archive-mcp -- npx -y telegram-archive-mcp`.
What does telegram-archive-mcp do?
It gives LLMs an interface to browse Telegram-Archive installations, run text searches, browse topics, and view post photos.
What is required before using the server?
An accessible Telegram-Archive viewer instance is required, along with viewer credentials configured under TELEGRAM_ARCHIVE_USER and TELEGRAM_ARCHIVE_PASS.
