- 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
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 invite_to_group function to the Chat & Group Management section
of the README. This function exists in main.py with @mcp.tool() decorator
but was missing from the documentation.
Add documentation for three new message reaction tools from PR #41:
- send_reaction(chat_id, message_id, emoji, big=False): Add a reaction to a message
- remove_reaction(chat_id, message_id): Remove a reaction from a message
- get_message_reactions(chat_id, message_id, limit=50): Get all reactions on a message
These tools are now part of the Messaging section in the features list.
Add new list_topics() MCP tool to retrieve forum topics from Telegram
supergroups with forum feature enabled.
Features:
- Validates chat is a supergroup with forum enabled
- Supports pagination via offset_topic parameter
- Supports search filtering via search_query parameter
- Returns comprehensive topic metadata:
* Topic ID and title
* Total messages and unread count
* Status flags (closed, hidden)
* Last activity timestamp
- Proper error handling and logging
Documentation:
- Added list_topics to README Messaging tools list
- Added complete code example with implementation
- Added example output showing typical usage
Uses Telethon's GetForumTopicsRequest API for reliable forum topic
retrieval from supergroups.
Adds a new `@validate_id` decorator to validate `chat_id` and `user_id` parameters in `main.py`.
This decorator ensures that all IDs passed to functions are in a valid format before making RPC calls to the Telegram API. It handles:
- Integer IDs (positive and negative)
- String representations of integer IDs
- Usernames (e.g., "@username")
- Lists of IDs
Key changes:
- Created a `validate_id` decorator in `main.py`.
- Applied the decorator to all functions that accept `chat_id`, `user_id`, or similar parameters.
- Updated the central `log_and_format_error` function to handle custom validation error messages and a specific `VALIDATION-001` error code for logging.
- Added a new test suite (`test_validation.py`) with comprehensive tests for the decorator.
- Updated `README.md` and `session_string_generator.py` with documentation about the new validation.
Renamed all instances of 'telegram-mcp-server' to 'telegram-mcp' in docker-compose.yml, README.md, and the Docker build workflow to ensure consistency and clarity across the project.
Added badges for Python linting and Docker build validation to the README.md, enhancing visibility of the project's continuous integration status and encouraging best practices in code quality and deployment.
Introduced a new section in the README.md detailing how to run the server using Docker, including steps for building the image and running the container with both Docker Compose and the `docker run` command. This enhances the documentation for users looking to simplify dependency management.
Removed several functions that required direct file path access, including `send_file`, `download_media`, `set_profile_photo`, `edit_chat_photo`, `send_voice`, `send_sticker`, and `upload_file`, due to limitations in the current MCP environment. Updated the README to reflect these changes and added a section on removed functionality.
- Added a "Basic usage example" section to enhance clarity on how to utilize the Telegram MCP capabilities.
- Improved the structure of the README for better readability and user guidance.
- Added a new section showcasing the Telegram MCP in action with screenshots.
- Included examples of interactions with Claude for analyzing chat history and sending messages.
- Enhanced overall documentation to improve user understanding of the Telegram integration.
- Enhanced logging setup in main.py for better error tracking and console output.
- Improved error handling in group and user management functions.
- Updated .env.example to include a sample session string and removed outdated test configurations.
- Expanded README.md with new tool examples and usage instructions for better clarity.
- Removed the test.py file as it is no longer needed for testing.
- Expanded .env.example to include detailed test configuration options for chat and user IDs.
- Updated README.md to reflect new testing instructions and configuration details.
- Improved documentation on error handling and robustness of the Telegram MCP server.
- Bumped version to 2.0.0 in pyproject.toml and updated dependencies.
- Expanded README.md to reflect new features, including comprehensive tools for chat, group, and contact management.
- Added new functionalities for managing contacts, messages, and user profiles.
- Updated .gitignore to include .DS_Store files.
- Improved error handling and messaging in main.py.
- Enhanced overall documentation and usage examples for better user guidance.
- Renamed section "Set Up Your Environment" to "Generate Session String" and moved it up in the order.
- Added detailed instructions for generating a session string using Telethon's StringSession.
- Updated the environment setup instructions to include the new session string variable.
- Updated .env.example with new Telegram API credentials and session string options.
- Expanded .gitignore to exclude session files and configuration.
- Refactored main.py to support string session authentication and added new functions for contact and message management.
- Updated README.md to reflect new features, installation instructions, and usage examples.
- Added python-dotenv as a dependency in pyproject.toml for environment variable management.
