Telegram-Archive-MCP

A tiny bridge that exposes any Telegram-Archive instance as an MCP server, enabling LLMs to search messages, browse chats, and access archived Telegram history.

What you get

Type	What for	MCP URI / Tool id
Resources	Browse archive stats, chats, and folders read-only	`telegram-archive://stats` `telegram-archive://chats` `telegram-archive://folders` `telegram-archive://health`
Tools	Search and retrieve messages, inspect chat statistics	`search_messages` `get_messages` `get_pinned_messages` `get_messages_by_date` `get_chat_stats` `get_topics` `refresh_stats`

Everything is exposed over a single JSON-RPC endpoint (/mcp). LLMs / Agents can: initialize -> readResource -> listTools -> callTool ... and so on.

Quick-start (Docker Compose)

hljs language-yaml

services:
  telegram-archive-mcp:
    image: drumsergio/telegram-archive-mcp:latest
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - TELEGRAM_ARCHIVE_URL=http://telegram-archive:3000
      - TELEGRAM_ARCHIVE_USER=your-username
      - TELEGRAM_ARCHIVE_PASS=your-password

Security note: The HTTP transport listens on 127.0.0.1:8080 by default. If you need to expose it on a network, place it behind a reverse proxy with authentication.

Install via npm (stdio transport)

hljs language-sh

npx telegram-archive-mcp

Or install globally:

hljs language-sh

npm install -g telegram-archive-mcp
telegram-archive-mcp

This downloads the pre-built Go binary from GitHub Releases for your platform and runs it with stdio transport. Requires at least one published release.

Local build

hljs language-sh

git clone https://github.com/GeiserX/telegram-archive-mcp
cd telegram-archive-mcp

# (optional) create .env from the sample
cp .env.example .env && $EDITOR .env

go run ./cmd/server

Configuration

Variable	Default	Description
`TELEGRAM_ARCHIVE_URL`	`http://localhost:3000`	Telegram-Archive instance URL (without trailing /)
`TELEGRAM_ARCHIVE_USER`	(empty)	Login username for session auth via `/api/login`
`TELEGRAM_ARCHIVE_PASS`	(empty)	Login password for session auth via `/api/login`
`LISTEN_ADDR`	`127.0.0.1:8080`	HTTP listen address (Docker sets `0.0.0.0:8080`)
`MCP_AUTH_TOKEN`	(empty)	Bearer token for HTTP auth (required if not loopback)
`TRANSPORT`	(empty = HTTP)	Set to `stdio` for stdio transport

Put them in a .env file (from .env.example) or set them in the environment.

Testing

Tested with Inspector and it is currently fully working. Before making a PR, make sure this MCP server behaves well via this medium.

Example configuration for client LLMs

hljs language-json

{
  "schema_version": "v1",
  "name_for_human": "Telegram-Archive-MCP",
  "name_for_model": "telegram_archive_mcp",
  "description_for_human": "Search messages, browse chats, and access archived Telegram history.",
  "description_for_model": "Interact with a Telegram-Archive instance that stores archived Telegram messages. First call initialize, then reuse the returned session id in header \"Mcp-Session-Id\" for every other call. Use readResource to fetch URIs that begin with telegram-archive://. Use listTools to discover available actions and callTool to execute them.",
  "auth": {
    "type": "bearer",
    "token": "<your MCP_AUTH_TOKEN value>"
  },
  "api": {
    "type": "jsonrpc-mcp",
    "url":  "http://localhost:8080/mcp",
    "init_method": "initialize",
    "session_header": "Mcp-Session-Id"
  },
  "contact_email": "acsdesk@protonmail.com",
  "legal_info_url": "https://github.com/GeiserX/telegram-archive-mcp/blob/main/LICENSE"
}

Credits

Telegram-Archive -- Telegram message archival and search

MCP-GO -- modern MCP implementation

GoReleaser -- painless multi-arch releases

Maintainers

@GeiserX.

Contributing

Feel free to dive in! Open an issue or submit PRs.

Telegram-Archive-MCP follows the Contributor Covenant Code of Conduct.

Other MCP Servers by GeiserX

cashpilot-mcp — Passive income monitoring
duplicacy-mcp — Backup health monitoring
genieacs-mcp — TR-069 device management
lynxprompt-mcp — AI configuration blueprints
pumperly-mcp — Fuel and EV charging prices

Related Projects

Project	Description
Telegram-Archive	Automated, incremental Telegram backups with a local web viewer
telegram-delay-channel-cloner	Telegram bot that relays messages between channels with configurable delay
telegram-slskd-local-bot	Automated music discovery and download via Telegram bot with Soulseek
paperless-telegram-bot	Manage Paperless-NGX documents entirely through Telegram
n8n-nodes-telegram-archive	n8n community node for Telegram-Archive

telegram-archive-mcp

Telegram-Archive-MCP

What you get

Quick-start (Docker Compose)

Install via npm (stdio transport)

Local build

Configuration

Testing

Example configuration for client LLMs

Credits

Maintainers

Contributing

Other MCP Servers by GeiserX

Related Projects

Similar Packages

Security

Tags

Original Author

Publisher