Telegram Archive Mcp
About
<h1 align="center">Telegram-Archive-MCP</h1> <p align="center"> <a href="https://www.npmjs.com/package/telegram-archive-mcp"><img src="https://img.shields.io/npm/v/telegram-archive-mcp?style=flat-square&logo=npm" alt="npm"/></a> <img…
Details
- Author
- GeiserX
- Downloads
- 383
- Categories
- Communication, Other, Search
Jump to
- Exposes archive stats, chats, and folders as read-only resources
- Provides search, retrieve, and statistics tools for messages
- Single JSON-RPC endpoint at /mcp
- Supports both HTTP and stdio transports
- Easy configuration via environment variables
- Available as Docker image and npm package
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Telegram Archive McpCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Deploy via Docker Compose or install with npx telegram-archive-mcp (or global npm install). Configure the Telegram-Archive instance URL and optional credentials via environment variables (TELEGRAM_ARCHIVE_URL, TELEGRAM_ARCHIVE_USER, TELEGRAM_ARCHIVE_PASS). The server runs an HTTP JSON-RPC endpoint on port 8080 (or stdio transport). Clients call initialize, then use readResource and callTool to interact.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"telegram archive mcp": {
"telegram-archive": {
"command": "npx",
"args": [
"-y",
"telegram-archive-mcp"
],
"env": {
"TELEGRAM_ARCHIVE_URL": "http://localhost:3000",
"TELEGRAM_ARCHIVE_USER": "",
"TELEGRAM_ARCHIVE_PASS": ""
}
}
}
}
}McpServers
{
"telegram-archive": {
"command": "npx",
"args": [
"-y",
"telegram-archive-mcp"
],
"env": {
"TELEGRAM_ARCHIVE_URL": "http://localhost:3000",
"TELEGRAM_ARCHIVE_USER": "",
"TELEGRAM_ARCHIVE_PASS": ""
}
}
}<h1 align="center">Telegram-Archive-MCP</h1>
<p align="center">
<a href="https://www.npmjs.com/package/telegram-archive-mcp">
<a href="https://hub.docker.com/r/drumsergio/telegram-archive-mcp">
<a href="https://github.com/GeiserX/telegram-archive-mcp/stargazers">
<a href="https://github.com/GeiserX/telegram-archive-mcp/blob/main/LICENSE">
</p>
<p align="center">
<a href="https://registry.modelcontextprotocol.io">
<a href="https://glama.ai/mcp/servers/GeiserX/telegram-archive-mcp">
</a>
<a href="https://mcpservers.org/servers/geiserx/telegram-archive-mcp">
<a href="https://mcp.so/server/telegram-archive-mcp">
<a href="https://github.com/toolsdk-ai/toolsdk-mcp-registry">
</p>
<p align="center"><strong>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.</strong></p>
---
What you get
| Type | What for | MCP URI / Tool id |
|---------------|----------------------------------------------------------------|----------------------------------|
| Resources | Browse archive stats, chats, and folders read-only | telegram-archive://stats<br>telegram-archive://chats<br>telegram-archive://folders<br>telegram-archive://health |
| Tools | Search and retrieve messages, inspect chat statistics | search_messages<br>get_messages<br>get_pinned_messages<br>get_messages_by_date<br>get_chat_stats<br>get_topics<br>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) |
| 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": "none" },
"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
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
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
