<h1 align="center">Telegram-Archive-MCP</h1>

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)

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)

npx telegram-archive-mcp

Or install globally:

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

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

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

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

Score

Proud of your score? Add this badge to your README.

telegram-archive-mcp FAQ

How do I install telegram-archive-mcp?

Is telegram-archive-mcp an official MCP server?

Related MCP servers

Related guides