# telegram-archive-mcp

![telegram-archive-mcp: let any AI agent search your Telegram archive](<https://geiserx.github.io/telegram-archive-mcp/images/banner.svg>)

[![npm](<https://img.shields.io/npm/v/telegram-archive-mcp?style=flat-square&amp;logo=npm>)](<https://www.npmjs.com/package/telegram-archive-mcp>) [![Docker Pulls](<https://img.shields.io/docker/pulls/drumsergio/telegram-archive-mcp?style=flat-square&amp;logo=docker>)](<https://hub.docker.com/r/drumsergio/telegram-archive-mcp>) [![GitHub Stars](<https://img.shields.io/github/stars/GeiserX/telegram-archive-mcp?style=flat-square&amp;logo=github>)](<https://github.com/GeiserX/telegram-archive-mcp/stargazers>) [![License: GPL-3.0-or-later](<https://img.shields.io/github/license/GeiserX/telegram-archive-mcp?style=flat-square>)](<https://github.com/GeiserX/telegram-archive-mcp/blob/main/LICENSE>)

---

**telegram-archive-mcp** lets Claude, Cursor or any other MCP client read the Telegram history you keep with [Telegram Archive](<https://geiserx.github.io/Telegram-Archive/>). Without it, the archive is a web viewer you search by hand, one chat at a time. With it, you ask the assistant "what was the address someone posted in the climbing group last spring?" and it finds the chat, searches it, reads the messages of the right day and answers from them. It signs in to your viewer the way a browser does, only reads, and runs as one Go binary with no database of its own. Start with [Getting started](<https://geiserx.github.io/telegram-archive-mcp/getting-started/index.md>), then [Usage](<https://geiserx.github.io/telegram-archive-mcp/usage/index.md>) for what the assistant can read.

- **[Getting started](<https://geiserx.github.io/telegram-archive-mcp/getting-started/index.md>)**

  ---

  `npx` for Claude Desktop, Cursor and Claude Code, the Docker image for a server over HTTP, or a local Go build.
- **[Connect your client](<https://geiserx.github.io/telegram-archive-mcp/configuration/#client-configuration>)**

  ---

  The `mcpServers` block for stdio, and the `url` block with a bearer token for a server you run over HTTP.
- **[Usage](<https://geiserx.github.io/telegram-archive-mcp/usage/index.md>)**

  ---

  The 4 resources and 12 tools, their arguments, paging through a long chat and reading one day at a time.
- **[Configuration](<https://geiserx.github.io/telegram-archive-mcp/configuration/index.md>)**

  ---

  Every environment variable and its default.

## What the assistant can read

- Your chats and folders, with the ids the other tools take, filtered by name, folder or archived state (`list_chats`, `list_folders`).
- Messages that contain a keyword, in every chat at once (`search_all_chats`) or in one chat (`search_messages`).
- The conversation around one message (`get_message_context`).
- A chat's messages, newest first, as far back as the archive goes (`get_messages`), or every message of one calendar day in your timezone (`get_messages_by_date`).
- Pinned messages, forum topics (and any tool's messages narrowed to one topic), per-chat statistics, and the archive's totals and health as resources.
- The photo attached to a message, as an image the model can look at, or the name, type and size of any other file (`get_media`).

The full list with every argument is on [Usage](<https://geiserx.github.io/telegram-archive-mcp/usage/index.md>).

## How it runs

```
flowchart LR
    C[MCP client<br/>Claude Desktop, Claude Code, Cursor, VS Code, Codex]
    S[telegram-archive-mcp<br/>one Go binary]
    V[Telegram Archive viewer<br/>HTTP API, port 8000]
    A[(Your archive)]
    C <-->|MCP over stdio or HTTP /mcp| S
    S <-->|HTTP, signed in with the viewer's login| V
    V --- A
```

- Over stdio the client starts the binary itself; that is what `npx -y telegram-archive-mcp` does, and it is the mode for a client on the same machine.
- Over HTTP the binary serves `/mcp` on `127.0.0.1:8080`. Listening on any other address requires `MCP_AUTH_TOKEN`, which clients then send as a bearer token. See [Configuration](<https://geiserx.github.io/telegram-archive-mcp/configuration/index.md>).
- It speaks MCP 2026-07-28 and every earlier revision down to 2024-11-05, so clients on either side of the 2026 protocol change work.
- It signs in with `TELEGRAM_ARCHIVE_USER` and `TELEGRAM_ARCHIVE_PASS` through the viewer's `/api/login`, keeps the session cookie in memory, and signs in again when it expires.
- The same version ships as Go binaries for Linux, macOS and Windows on amd64 and arm64, the npm package and the Docker image `drumsergio/telegram-archive-mcp`.

## What it does not do

- It never talks to Telegram. It reads what your Telegram Archive backup has already saved, so a message the backup has not fetched yet is not there.
- It never sends, edits or deletes a message, in Telegram or in the archive. The one call that asks the viewer to do work is `refresh_stats`, which recalculates the statistics; `READ_ONLY=1` hides it.
- It stores nothing. No database and no cache; every answer is read from the viewer when it is asked for.

## Privacy

- Message text is written by other people, and a message can be worded to look like an instruction. The server tells the model to treat it as data, but keep your client's approval prompts on for tools from other servers.
- Every message and image a tool returns goes into your MCP client's conversation, and from there to the model the client uses. With a hosted model, that provider receives those messages. Point the server at an archive you are willing to share that way, and keep your client's tool-approval prompts on.
- The server logs its version and its listen address, never message text, chat names or credentials.
- Over stdio, the viewer's password sits in your client's configuration file. Over HTTP, it stays on the machine that runs the server.

## Getting help

- A tool answers `login failed` with a status code: `TELEGRAM_ARCHIVE_USER` or `TELEGRAM_ARCHIVE_PASS` does not match a viewer login. See [Configuration](<https://geiserx.github.io/telegram-archive-mcp/configuration/index.md>).
- Every call fails with a connection error: `TELEGRAM_ARCHIVE_URL` does not reach the viewer. Inside Docker Compose it is the viewer's service name, as in [Getting started](<https://geiserx.github.io/telegram-archive-mcp/getting-started/#docker-compose-http>).
- The server exits with `MCP_AUTH_TOKEN is required when LISTEN_ADDR is not loopback`: set a token, or listen on `127.0.0.1`.
- Something else: open an [issue](<https://github.com/GeiserX/telegram-archive-mcp/issues>) with the server's log lines. A security problem goes through the [security policy](<https://github.com/GeiserX/telegram-archive-mcp/blob/main/SECURITY.md>), never a public issue.
- Building, testing with MCP Inspector and sending a fix: [Development](<https://geiserx.github.io/telegram-archive-mcp/development/index.md>). Telegram Archive itself, other MCP servers and where this one is listed: [Related projects](<https://geiserx.github.io/telegram-archive-mcp/related/index.md>).

## License

telegram-archive-mcp is released under the [GPL-3.0-or-later](<https://github.com/GeiserX/telegram-archive-mcp/blob/main/LICENSE>) license. It is built on [mcp-go](<https://github.com/mark3labs/mcp-go>).
