How do I install Telegram Archive?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Telegram Archive need an API key?

The publisher lists these environment variables: TELEGRAM_ARCHIVE_URL, TELEGRAM_ARCHIVE_USER, TELEGRAM_ARCHIVE_PASS, READ_ONLY.

What transport does Telegram Archive use?

Telegram Archive runs locally over stdio.

When was Telegram Archive last checked?

Last checked 2026-11-11. Search and read your archived Telegram chats and messages

Telegram Archive MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y [email protected]

Credentials from the publisher

TELEGRAM_ARCHIVE_URL — Telegram Archive instance URL (e.g. http://localhost:8000)
TELEGRAM_ARCHIVE_USER — Telegram Archive login username
TELEGRAM_ARCHIVE_PASS — Telegram Archive login password
READ_ONLY — Set to true to hide refresh_stats, the one tool that asks the viewer to do work

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1TELEGRAM_ARCHIVE_URL=<value> TELEGRAM_ARCHIVE_USER=<value> TELEGRAM_ARCHIVE_PASS=<secret> READ_ONLY=<value> claude mcp add io.github.geiserx-telegram-archive-mcp -- npx -y telegram-archive-mcp@0.4.1

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.geiserx-telegram-archive-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "[email protected]"8      ],9      "env": {10        "TELEGRAM_ARCHIVE_URL": "<value>",11        "TELEGRAM_ARCHIVE_USER": "<value>",12        "TELEGRAM_ARCHIVE_PASS": "<secret>",13        "READ_ONLY": "<value>"14      }15    }16  }17}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

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

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:

{
  "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.

Documentation

The full documentation is at geiserx.github.io/telegram-archive-mcp.

Getting started: npm, Docker Compose, local build
Configuration: environment variables and client configuration
Usage: the 4 resources and 10 tools, paging, reading one day at a time
Development: testing, contributing, credits
Related projects: Telegram Archive, other MCP servers, where this one is listed

License

GPL-3.0-or-later