This server bridges a Telegram-Archive instance to the Model Context Protocol, enabling LLMs to search, browse, and retrieve archived Telegram messages, chats, and statistics.
Tools:
search_messages: Search for messages in a specific chat by keyword, with a configurable result limit.
get_messages: Retrieve paginated messages from a chat using limit and offset parameters.
get_messages_by_date: Fetch messages from a chat on a specific date (YYYY-MM-DD), with optional IANA timezone support.
get_pinned_messages: Retrieve all pinned messages from a specific chat.
get_topics: List forum threads/topics from a specific chat.
get_chat_stats: View statistics for a specific chat.
refresh_stats: Force a recalculation of global archive statistics.
Resources (via telegram-archive:// URIs):
Browse archive-wide stats, list of chats, folders, and health status of the connected Telegram-Archive instance.
Enables searching archived Telegram messages, browsing chats and folders, and retrieving chat statistics through a Telegram-Archive instance.
Type | What for | MCP URI / Tool id |
Resources | Browse archive stats, chats, and folders read-only |
|
Tools | Search and retrieve messages, inspect chat statistics |
|
Everything is exposed over a single JSON-RPC endpoint (/mcp).
LLMs / Agents can: initialize -> readResource -> listTools -> callTool ... and so on.
Related MCP server: telegram-mcp
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-passwordSecurity note: The HTTP transport listens on
127.0.0.1:8080by default. If you need to expose it on a network, place it behind a reverse proxy with authentication.
npx telegram-archive-mcpOr install globally:
npm install -g telegram-archive-mcp
telegram-archive-mcpThis downloads the pre-built Go binary from GitHub Releases for your platform and runs it with stdio transport. Requires at least one published release.
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/serverVariable | Default | Description |
|
| Telegram-Archive instance URL (without trailing /) |
| (empty) | Login username for session auth via |
| (empty) | Login password for session auth via |
|
| HTTP listen address (Docker sets |
| (empty) | Bearer token for HTTP auth (required if not loopback) |
| (empty = HTTP) | Set to |
Put them in a .env file (from .env.example) or set them in the environment.
Tested with Inspector and it is currently fully working. Before making a PR, make sure this MCP server behaves well via this medium.
{
"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"
}Telegram-Archive -- Telegram message archival and search
MCP-GO -- modern MCP implementation
GoReleaser -- painless multi-arch releases
Feel free to dive in! Open an issue or submit PRs.
Telegram-Archive-MCP follows the Contributor Covenant Code of Conduct.
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
Project | Description |
Automated, incremental Telegram backups with a local web viewer | |
Telegram bot that relays messages between channels with configurable delay | |
Automated music discovery and download via Telegram bot with Soulseek | |
Manage Paperless-NGX documents entirely through Telegram | |
n8n community node for Telegram-Archive |
Get statistics for a specific Telegram chat
| Name | Required | Description | Default |
|---|---|---|---|
| chat_id | Yes | Chat ID to get statistics for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Omits explanation of why destructiveHint=true (unusual for a GET operation) or what side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely brief with no fluff, though arguably too minimal for the complexity signaled by annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing critical context: no output schema exists, destructive behavior unexplained, and 'statistics' type unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds no parameter details, but schema coverage is 100% so meets baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States basic function ('Get statistics') but is vague about what statistics and fails to distinguish from sibling 'refresh_stats'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this versus refresh_stats or other data retrieval tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get messages from a Telegram chat with pagination
| Name | Required | Description | Default |
|---|---|---|---|
| chat_id | Yes | Chat ID to retrieve messages from | |
| limit | No | Maximum messages to return (default 50) | |
| offset | No | Pagination offset (default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotation Contradiction: Description implies a safe read operation ('Get messages'), but annotations indicate destructiveHint=true and readOnlyHint=false without explanation for this dangerous mismatch.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise and front-loaded, though potentially too terse given the behavioral complexity and annotation warnings that require explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Incomplete given the destructive annotation flag and sibling complexity; omits critical safety warnings and output expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage; description adds no parameter semantics but meets baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States basic function (retrieving messages with pagination) but fails to differentiate from siblings like search_messages or get_messages_by_date.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to prefer this over alternative message retrieval tools or specific use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get messages from a Telegram chat on a specific date
| Name | Required | Description | Default |
|---|---|---|---|
| chat_id | Yes | Chat ID to retrieve messages from | |
| date | Yes | Date in YYYY-MM-DD format | |
| timezone | No | IANA timezone (e.g. Europe/Madrid). Optional. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Fails to explain destructiveHint=true annotation (critical for a 'get' operation, likely marks messages as read).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise (9 words), front-loaded, no fluff, though brevity sacrifices necessary behavioral details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks description of return values needed given no output schema exists; adequate for simple parameter set but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage; description adds no new parameter context, meeting baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear specific verb (Get) and resource (messages from Telegram chat), distinguishes from sibling get_messages via 'on a specific date' qualifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus get_messages or search_messages siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get pinned messages from a Telegram chat
| Name | Required | Description | Default |
|---|---|---|---|
| chat_id | Yes | Chat ID to get pinned messages from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotation Contradiction: Description uses 'Get' implying read-only operation, but annotations specify destructiveHint: true with no explanation of what state changes occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise (6 words) and front-loaded with action verb; appropriate for single-parameter tool though lacks structural complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks description of return values or output format, which is notable given no output schema exists, though basic functionality is covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage ('Chat ID to get pinned messages from'), and description adds no further parameter semantics, meeting baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb and resource ('Get pinned messages'), and specifies 'pinned' which distinguishes it from sibling get_messages/search_messages, though could explicitly contrast with alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus get_messages or search_messages, nor mention that pinned messages are a specific subset.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get topics (forum threads) from a Telegram chat
| Name | Required | Description | Default |
|---|---|---|---|
| chat_id | Yes | Chat ID to get topics from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotation Contradiction: Description implies harmless retrieval with 'Get' but annotations mark destructiveHint=true with no explanation for why retrieval is destructive; ignores openWorldHint implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise and front-loaded, though brevity comes at cost of omitting critical behavioral context implied by annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists yet description fails to indicate return structure; does not address destructive nature or side effects flagged in annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage for chat_id; description adds no parameter details but meets baseline given comprehensive schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Get' and resource 'topics (forum threads)' distinguishes from message-oriented siblings, though explicit differentiation from get_messages would strengthen it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use topics vs messages or other retrieval alternatives; lacks when/when-not context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Force recalculation of global telegram-archive statistics
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds 'global' scope and clarifies that the destructive operation performs a recalculation (not deletion), complementing the destructive=true annotation without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single front-loaded sentence where every word ('Force', 'global', 'recalculation') earns its place; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a parameterless tool; covers action, scope, and domain sufficiently given the lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero-parameter tool triggers baseline score of 4; schema requires no additional semantic elaboration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear specific action (force recalculation) and target (global telegram-archive statistics), implicitly distinguishing from sibling get_chat_stats by emphasizing 'recalculation' vs 'get'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'Force' implies usage when fresh data is needed, but lacks explicit when-to-use guidance or contrast with retrieval alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search messages in a Telegram chat by keyword
| Name | Required | Description | Default |
|---|---|---|---|
| chat_id | Yes | Chat ID to search in | |
| limit | No | Maximum results to return (default 20) | |
| query | Yes | Search query string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Fails to explain why a search operation is marked destructive=true in annotations, or what openWorldHint implies for search scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely terse at 6 words; while front-loaded, it lacks necessary detail given the destructive hint and complex sibling relationships.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing critical context: no explanation of return value structure (no output schema), pagination behavior, or the counter-intuitive destructive classification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the description meets baseline expectations but adds no additional parameter context (e.g., query syntax, limit constraints).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool searches messages by keyword in a Telegram chat, distinguishing it from sibling 'get' tools that retrieve messages by date or pinned status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use search vs. get_messages or get_messages_by_date, nor any exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0get_chat_statsget_messagesget_messages_by_dateget_pinned_messagesget_topicsrefresh_statssearch_messagesThe message retrieval tools (get_messages, get_messages_by_date, get_pinned_messages, search_messages) have distinct filtering purposes that agents can distinguish, though there's slight overlap between general pagination and date-specific retrieval. get_chat_stats and refresh_stats are clearly differentiated by scope (specific chat vs global).
Most tools follow a consistent snake_case verb_noun pattern with 'get_' prefix (get_messages, get_topics), but refresh_stats breaks this convention by using 'refresh' instead of 'get' or 'update'. search_messages appropriately uses 'search' to distinguish from retrieval operations.
Seven tools is well-suited for a focused archive access server. Each tool serves a distinct retrieval pattern (pagination, date filter, search, pinned, topics, stats) without bloat. The count supports the core read-only archive workflow effectively.
The surface covers essential read operations for message archives including filtering, search, and statistics. Minor gaps include the absence of a list_chats discovery tool (assuming chat IDs are known) and no media/file download capability, though these may be out of scope for a text-focused archive.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
MCP server for AI dialogue using various LLM models via AceDataCloud
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/GeiserX/telegram-archive-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
