Overview

This MCP (Model Context Protocol) server exposes Telegram channels and groups as a toolable data source for LLMs and developer apps. It supports two retrieval modes: using the official Telegram API for high-performance access, and a web-scraping fallback for environments where API keys or sessions are not available. The server turns Telegram posts into structured responses you can call from an LLM (for example, Claude) or from your backend, enabling unlimited post retrieval and in-model search.

The main benefit is combining fast, paginated access (Telegram API path) with flexible scraping so you can index or query channel history without manual export. The server speaks a simple HTTP/MCP interface so it can be plugged into tool-enabled models or used directly from code.

Features

Two retrieval modes: official Telegram API (fast) and web scraping (no API keys required)
MCP-compatible JSON tool responses for integration with LLMs (Claude, etc.)
Full-text search across channel/group messages
Unlimited paginated post retrieval (subject to Telegram limits)
Simple HTTP endpoints for fetch, search and metadata
Docker-ready and configurable via environment variables

Installation / Configuration

Prerequisites:

Docker (recommended) or Node.js runtime depending on distribution
Telegram API credentials (optional, required for API mode): api_id, api_hash
A host URL or IP to call the server from your app/model runtime

Clone and run (Docker example):

git clone https://github.com/DLHellMe/telegram-mcp-server.git
cd telegram-mcp-server

# Example: run with Docker Compose (if provided)
docker compose up -d

Environment variables (example):

# Optional: use official Telegram API for fast access
TELEGRAM_API_ID=123456
TELEGRAM_API_HASH=abcdef1234567890abcdef1234567890

# If you prefer scraping instead of API
SCRAPING_MODE=true

# Server settings
PORT=8080
BASE_URL=http://0.0.0.0:8080

Run with Docker (single container):

docker run -d \
  -e TELEGRAM_API_ID=$TELEGRAM_API_ID \
  -e TELEGRAM_API_HASH=$TELEGRAM_API_HASH \
  -e SCRAPING_MODE=$SCRAPING_MODE \
  -p 8080:8080 \
  dlhellme/telegram-mcp-server:latest

After startup, the server exposes HTTP endpoints (see below). Substitute BASE_URL with your server address.

Available Resources

The server provides HTTP endpoints to discover tools, fetch posts and run searches. Common endpoints:

Endpoint	Purpose	Input
GET /health	Health check	none
GET /tools	List available MCP tools	none
POST /fetch	Retrieve posts from a channel/group	{ channel, limit, before_id }
POST /search	Search messages	{ channel, query, limit }
GET /meta	Channel metadata (title, description)	?channel=@channelname

Example: fetch latest 50 posts

curl -X POST "$BASE_URL/fetch" \
  -H "Content-Type: application/json" \
  -d '{"channel":"@example_channel","limit":50}'

Example: full-text search in a group

curl -X POST "$BASE_URL/search" \
  -H "Content-Type: application/json" \
  -d '{"channel":"@example_channel","query":"price update","limit":20}'

Responses are JSON lists of messages with timestamps, sender info and text content suitable for indexing or direct model input.

MCP Tool Definition (for LLMs)

To call the server from a model that supports the MCP/tool invocation pattern, expose a tool like this (JSON pseudocode):

{
  "name": "telegram_search",
  "description": "Search a Telegram channel or group and return matching posts with metadata",
  "parameters": {
    "type": "object",
    "properties": {
      "channel": {"type": "string"},
      "query": {"type": "string"},
      "limit": {"type": "integer"}
    },
    "required": ["channel", "query"]
  }
}

When the model invokes this tool, your agent/controller should forward the call to POST /search and return the structured results back to the model.

Use Cases

Research & summarization: Ask an LLM to search a channel for specific topics, then generate summaries or timelines from returned posts.
- Example: “Find posts about ‘v2.0 release’ in @project_updates and summarize changes.”
Monitoring & alerts: Periodically fetch the latest posts and run keyword-based checks to trigger notifications.
- Example: fetch latest 100 posts, alert on mentions of “outage” or “incident”.
Data collection & indexing: Bulk-retrieve historical posts (API mode recommended) to build an internal search index or dataset for training.
- Example: run /fetch with pagination to export full channel history.
In-chat retrieval for assistants: Wire the MCP tool into Claude or another model so the assistant can pull in recent channel posts on demand and provide answers grounded in that content.

Tips & Best Practices

Prefer the official Telegram API path for bulk operations (much faster and more stable). Use scraping as a fallback.
Respect Telegram terms of service when scraping and rate-limit requests.
When integrating with an LLM, return compact structured results (timestamp, author, text, id) to keep context efficient.
Use pagination (before_id/after_id) for long histories to avoid large single responses.

For full implementation details, examples and the latest updates, see the project on GitHub: https://github.com/DLHellMe/telegram-mcp-server.

Telegram MCP Server: API, Scraping, Search