Display unread_mentions_count for each chat when it is greater than zero.
The value is already available on the dialog object from Telegram API,
so this adds no extra API calls.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add filtering capabilities to the list_chats tool:
- unread_only: filter to show only chats with unread messages
- unmuted_only: filter to show only unmuted chats
- Display mute status in chat info output
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Address review feedback from @chigwell and @l1v0n1:
- Restore parse_mode=parse_mode in send_message and reply_to_message
- Restore _resolve_readable_file_path() in send_file, send_voice,
send_sticker, and edit_chat_photo
- Use str(safe_path) instead of raw file_path in upload_file calls
The entity cache fix (resolve_entity/resolve_input_entity) is preserved
in all affected functions.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
StringSession has no persistent entity cache. After each MCP server
restart, client.get_entity(positive_int) fails for basic group chats
because Telethon interprets positive integers as PeerUser IDs when
they're not in the cache.
Fix:
- Add resolve_entity() / resolve_input_entity() helpers that retry
after warming cache via get_dialogs() on ValueError
- Warm entity cache on startup in _main()
- Replace all ~72 client.get_entity() / client.get_input_entity()
call sites with the new helpers
Tested: 60/60 pass across 6 basic group chats (send_message,
get_history, reply, edit, draft, reactions, search, mark_as_read,
delete) with cold cache -> warm cache transition verified.
Fixeschigwell/telegram-mcp#76
contacts.SearchRequest returns both result.users and result.chats,
but only users were returned. Chats (channels, groups) are now
included, making search work by channel/group title as intended.
Shared folders in Telegram use DialogFilterChatlist type instead of
DialogFilter. Previously, all folder operations (list, get, create,
add/remove chat) silently ignored shared folders. This fix ensures
they are recognized and handled correctly alongside regular folders.
MCP clients (e.g. ZeroClaw) communicate via JSON-RPC over stdin/stdout.
Startup messages and warnings written to stdout corrupt the protocol
stream, causing parse failures. Redirect all print() calls to stderr.
Telethon's DeletePhotosRequest requires InputPhoto objects, which it derives
from Photo objects via get_input_photo(). Passing photo.id (an int) causes:
AttributeError: 'int' object has no attribute 'SUBCLASS_OF_ID'
TypeError: Cannot cast int to any kind of InputPhoto.
Fix: pass the Photo object directly (photos.photos[0]) so Telethon can
convert it to InputPhoto internally.
- implement server-side allowlist via CLI positional roots (fallback)\n- implement client MCP Roots override semantics (replace server roots when available)\n- add realpath + in-root validation, traversal/glob rejection, extension and size checks\n- make write path default to <first_root>/downloads when file_path is omitted\n- reintroduce upload_file tool with the same path security model\n- update README with security model and usage\n- add tests for root resolution, replacement semantics, traversal checks, and default write path\n- add pytest and pytest-asyncio to dev dependencies
archive_chat and unarchive_chat were using ToggleDialogPinRequest which
pins/unpins dialogs instead of archiving them. Replace with
folders.EditPeerFoldersRequest using folder_id=1 (Archive) and
folder_id=0 (Main) which is the correct API for moving chats to/from
the Archive folder.
- Changed phone parameter to Optional[str] = None
- Added separate username parameter (Optional[str] = None)
- Improved function signature clarity - username is now explicit parameter
- Updated validation logic to check for either phone or username
- Maintains backward compatibility with phone-based contacts
- Better API design - no longer need to pass username via phone parameter
- Modified add_contact function to support username-based contact addition
- If phone parameter is empty or starts with @, function resolves username first
- Uses contacts.AddContactRequest API for username-based contacts
- Maintains backward compatibility with phone-based contact addition
- Allows adding contacts as done in Telegram UI when searching by username
Add new MCP tools to manage Telegram dialog folders (filters):
- list_folders: get all folders with IDs, names, emoji
- get_folder: get folder details including all included chats
- create_folder: create new folder with filters and chat list
- add_chat_to_folder: add chat to existing folder (idempotent)
- remove_chat_from_folder: remove chat from folder (idempotent)
- delete_folder: delete folder (chats preserved)
- reorder_folders: change folder order
Handles Telegram API specifics:
- TextWithEntities for folder titles
- Max 10 folders limit
- System folder protection (ID < 2)
- title_noanimate and color attributes
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds views, forwards, and reaction counts to message output for channel posts.
These metrics are available in Telegram's API for channel content.
Changes:
- get_messages: Include engagement info in output
- list_messages: Include engagement info in output
Example output: 'views:1234, forwards:56, reactions:78'
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The individual line suggestions created invalid Python when applied
separately. Combined the ternary expression properly.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Previously list_chats only checked dialog.unread_count, missing chats
that were manually marked as unread via Telegram's "mark as unread" feature.
Now also checks dialog.dialog.unread_mark flag:
- unread_count > 0: shows "Unread: N"
- unread_mark = True: shows "Unread: marked"
This matches the behavior of Telegram's "Unread" folder filter.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add three new tools for managing Telegram drafts:
- save_draft: Save a draft message to any chat/channel
- get_drafts: List all drafts across all chats
- clear_draft: Clear a draft from a specific chat
Uses Telethon's SaveDraftRequest and GetAllDraftsRequest APIs.
Drafts appear in Telegram's input field for review before sending.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add three new MCP tools for handling Telegram message reactions:
- send_reaction: Send emoji reaction to a message
- remove_reaction: Remove your reaction from a message
- get_message_reactions: Get list of reactions on a message
All tools include proper ToolAnnotations and follow existing code patterns.
Add human-readable title annotations to all MCP tools to help clients
display tool names in a user-friendly format.
Changes:
- Added title annotation to all 78 tools (e.g., "Get Chats", "Send Message")
- Formatted with Black for code style consistency
This improves the user experience when MCP clients display tool lists.
Co-Authored-By: Claude <noreply@anthropic.com>
