Telegram MCP Server

MCP server for searching Telegram group messages.

Setup

1. Install dependencies:

2. Get Telegram API credentials from https://my.telegram.org

3. Create .env file:

4. Edit .env with your credentials:

Note: Group configuration is no longer required! The server now automatically discovers and searches all groups/channels the authenticated user belongs to (up to 50 by default, max 200 configurable).

5. Authenticate with Telegram:

This will prompt for a verification code and save the session to .env.

6. Build:

OpenCode Configuration

Add to opencode.json:

Replace /absolute/path/to/telegram-mcp with the actual path.

Usage

The server exposes a search_messages tool that automatically discovers and searches all groups/channels you belong to.

Automatic Group Discovery

By default, the tool automatically discovers and searches across:

• All groups and channels you're a member of

• Up to 50 groups (configurable up to 200)

• Active (non-archived) chats only

• All group types: channels, supergroups, gigagroups, and basic groups

Parameters

Basic Search:

• query (string, required) - Search keyword or phrase

• limit (number, optional) - Max results (default: 10, max: 100)

• offset (number, optional) - Pagination offset (default: 0)

• sortBy (string, optional) - Sort order: relevance (default), date_desc, date_asc

Date Filtering:

• startDate (string, optional) - Filter messages after this date

• endDate (string, optional) - Filter messages before this date

• dateRange (string, optional) - Convenience shortcuts: last24h, last7days, last30days, last90days

Auto-Discovery Options:

• maxGroups (number, optional) - Max groups to discover (default: 50, max: 200)

• includeChannels (boolean, optional) - Include channels (default: true)

• includeArchivedChats (boolean, optional) - Include archived chats (default: false)

• groupTypes (array, optional) - Filter by types: ["channel", "supergroup", "gigagroup", "basicgroup"] (default: all)

Specific Group Search:

• groupIds (array, optional) - Search specific groups only (skips auto-discovery). Format: numeric IDs (e.g., "-1001234567890") or usernames (e.g., "my_channel")

Performance:

• concurrencyLimit (number, optional) - Max parallel group searches (1-10, default: 3)

• rateLimitDelay (number, optional) - Delay between API requests in ms (0-5000, default: 1000)

Extended Data:

• includeExtendedMetadata (boolean, optional) - Include reactions, views, edit history (default: false)

Date Filtering

The date parameters support multiple formats:

1. ISO 8601: "2024-01-15T10:30:00Z"

2. Unix timestamp: 1705317000 (seconds or milliseconds)

3. Natural language: "3 days ago", "last week", "yesterday", "2 weeks ago"

4. Shortcuts: last24h, last7days, last30days, last90days

Date Priority: startDate/endDate parameters override dateRange if both are provided.

Extended Metadata

When includeExtendedMetadata is true, results include:

• Reactions: Emoji reactions with counts

• View counts: Number of views (for channel messages)

• Edit history: Indicates if message was edited and when

• Pinned status: Whether the message is pinned

• Reply context: Information about replied messages (ID, sender, text snippet)

• Forward information: Details if message was forwarded (source chat, message ID, date)

• Media attachments: Type, filename, mime type, size for photos, videos, documents

Note: Extended metadata requires additional API calls and may impact performance. Use only when needed.

Examples

Basic auto-discovery search (searches all your groups):

Search with date range:

Search with custom dates:

Natural language dates:

Advanced search with metadata:

Sort by date (newest first):

Sort by date (oldest first):

Search more groups (up to 200):

Search only channels:

Search specific groups only (skip auto-discovery):

Search with custom performance settings:

Search including archived chats:

Message Results

Each message result now includes group context:

This makes it easy to see which group each message came from!

Migration Guide

Upgrading from Previous Versions

What Changed:

• Group configuration is no longer required in .env

• The server now automatically discovers all your groups

• TELEGRAM_GROUP_ID and TELEGRAM_GROUP_IDS environment variables are no longer used

• Message results now include groupId, groupTitle, and groupType fields

Migration Steps:

1. Update your (optional):

   • You can remove TELEGRAM_GROUP_ID and TELEGRAM_GROUP_IDS entries

   • They won't cause errors if left in place, but are no longer used

2. Update your (optional):

   • Remove TELEGRAM_GROUP_ID from the environment section

   • Example updated config shown above

3. No code changes needed:

   • Auto-discovery works automatically

   • If you want to search specific groups, use the groupIds parameter in your search queries

4. New features to try:

   • maxGroups: Control how many groups to discover (default 50, max 200)

   • groupTypes: Filter by group type (channels, supergroups, etc.)

   • includeChannels: Toggle channel inclusion

   • includeArchivedChats: Include archived chats if needed

Backward Compatibility:

• All existing search queries work without changes

• The groupIds parameter still works for searching specific groups

• No breaking changes to message result format (only additive fields)

License

MIT