Telegram MCP Server
MCP server for searching Telegram group messages.
Setup
- Install dependencies:
npm install
-
Get Telegram API credentials from https://my.telegram.org
-
Create
.envfile:
cp .env.example .env
- Edit
.envwith your credentials:
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_PHONE=+1234567890
TELEGRAM_SESSION=
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).
- Authenticate with Telegram:
npm run auth
This will prompt for a verification code and save the session to .env.
- Build:
npm run build
OpenCode Configuration
Add to opencode.json:
{
"mcp": {
"telegram": {
"type": "local",
"command": ["node", "/absolute/path/to/telegram-mcp/dist/src/index.js"],
"environment": {
"TELEGRAM_API_ID": "{env:TELEGRAM_API_ID}",
"TELEGRAM_API_HASH": "{env:TELEGRAM_API_HASH}",
"TELEGRAM_PHONE": "{env:TELEGRAM_PHONE}",
"TELEGRAM_SESSION": "{env:TELEGRAM_SESSION}"
},
"enabled": true
}
}
}
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 phraselimit(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 dateendDate(string, optional) - Filter messages before this datedateRange(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:
- ISO 8601:
"2024-01-15T10:30:00Z" - Unix timestamp:
1705317000(seconds or milliseconds) - Natural language:
"3 days ago","last week","yesterday","2 weeks ago" - 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 for "deployment" using the telegram tool
Search with date range:
Search for "error" in the last 7 days sorted by relevance
Search with custom dates:
Search for "meeting" between 2024-01-01 and 2024-01-15
Natural language dates:
Search for "standup" from 3 days ago to yesterday
Advanced search with metadata:
Search for "announcement" with extended metadata in the last month, sorted by date
Sort by date (newest first):
Search for "release" sorted by date_desc
Sort by date (oldest first):
Search for "bug" sorted by date_asc in the last 30 days
Search more groups (up to 200):
Search for "deployment" with maxGroups=100
Search only channels:
Search for "announcement" with groupTypes=["channel"]
Search specific groups only (skip auto-discovery):
Search for "deployment" in specific groups: ["@group1", "@group2", "-1001234567890"]
Search with custom performance settings:
Search for "error" with concurrency limit 5 and 500ms delay between requests
Search including archived chats:
Search for "old discussion" including archived chats
Message Results
Each message result now includes group context:
{
"messageId": 12345,
"text": "Check out this vendor...",
"senderName": "John Doe",
"groupId": "-1001234567890",
"groupTitle": "Research Group",
"groupType": "supergroup",
"date": "2024-01-15T10:30:00Z",
"link": "https://t.me/c/1234567890/12345"
}
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_IDandTELEGRAM_GROUP_IDSenvironment variables are no longer used- Message results now include
groupId,groupTitle, andgroupTypefields
Migration Steps:
-
Update your
.envfile (optional):- You can remove
TELEGRAM_GROUP_IDandTELEGRAM_GROUP_IDSentries - They won't cause errors if left in place, but are no longer used
- You can remove
-
Update your
opencode.json(optional):- Remove
TELEGRAM_GROUP_IDfrom the environment section - Example updated config shown above
- Remove
-
No code changes needed:
- Auto-discovery works automatically
- If you want to search specific groups, use the
groupIdsparameter in your search queries
-
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 inclusionincludeArchivedChats: Include archived chats if needed
Backward Compatibility:
- All existing search queries work without changes
- The
groupIdsparameter still works for searching specific groups - No breaking changes to message result format (only additive fields)
License
MIT