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 ```sh 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: ```json { "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](https://geiserx.github.io/telegram-archive-mcp/getting-started/). ## Documentation The full documentation is at [geiserx.github.io/telegram-archive-mcp](https://geiserx.github.io/telegram-archive-mcp/). - [Getting started](https://geiserx.github.io/telegram-archive-mcp/getting-started/): npm, Docker Compose, local build - [Configuration](https://geiserx.github.io/telegram-archive-mcp/configuration/): environment variables and client configuration - [Usage](https://geiserx.github.io/telegram-archive-mcp/usage/): the 4 resources and 10 tools, paging, reading one day at a time - [Development](https://geiserx.github.io/telegram-archive-mcp/development/): testing, contributing, credits - [Related projects](https://geiserx.github.io/telegram-archive-mcp/related/): Telegram Archive, other MCP servers, where this one is listed ## License [GPL-3.0-or-later](https://github.com/GeiserX/telegram-archive-mcp/blob/main/LICENSE)