feat: major update to Telegram MCP server with new features and enhancements
- 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.
This commit is contained in:
anonim
parent
cab205f03d
commit
84de77230b
6 changed files with 1129 additions and 147 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -187,3 +187,4 @@ anon_new.session-journal
|
||||||
|
|
||||||
# Claude Desktop config
|
# Claude Desktop config
|
||||||
claude_desktop_config.json
|
claude_desktop_config.json
|
||||||
|
.DS_Store
|
||||||
|
|
|
||||||
277
README.md
277
README.md
|
|
@ -1,68 +1,142 @@
|
||||||
# Telegram MCP for Claude
|
# Telegram MCP Server
|
||||||
|
|
||||||
|
|
||||||
[](https://opensource.org/licenses/Apache-2.0)
|
[](https://opensource.org/licenses/Apache-2.0)
|
||||||
|
|
||||||
A powerful Telegram integration for Claude via the Model Context Protocol (MCP), allowing you to interact with your Telegram account directly from Claude Desktop.
|
A full-featured Telegram integration for Claude, Cursor, and any MCP-compatible client, powered by [Telethon](https://docs.telethon.dev/) and the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). This project lets you interact with your Telegram account programmatically, automating everything from messaging to group management.
|
||||||
|
|
||||||
|
**Maintained by [l1v0n1](https://github.com/l1v0n1). Forked from [chigwell/telegram-mcp](https://github.com/chigwell/telegram-mcp).**
|
||||||
|
|
||||||
## 🚀 Features
|
---
|
||||||
|
|
||||||
This MCP server provides a comprehensive suite of tools for seamless Telegram interaction:
|
## 🚀 Features & Tools
|
||||||
|
|
||||||
### Chat Management
|
This MCP server exposes a huge suite of Telegram tools. **Every major Telegram/Telethon feature is available as a tool!**
|
||||||
- **get_chats** - Get a paginated list of your chats
|
|
||||||
- **list_chats** - List all chats with detailed metadata and filtering options
|
### Chat & Group Management
|
||||||
- **get_chat** - Get detailed information about a specific chat
|
- **get_chats(page, page_size)**: Paginated list of chats
|
||||||
|
- **list_chats(chat_type, limit)**: List chats with metadata and filtering
|
||||||
|
- **get_chat(chat_id)**: Detailed info about a chat
|
||||||
|
- **create_group(title, user_ids)**: Create a new group
|
||||||
|
- **create_channel(title, about, megagroup)**: Create a channel or supergroup
|
||||||
|
- **edit_chat_title(chat_id, title)**: Change chat/group/channel title
|
||||||
|
- **edit_chat_photo(chat_id, file_path)**: Set chat/group/channel photo
|
||||||
|
- **delete_chat_photo(chat_id)**: Remove chat/group/channel photo
|
||||||
|
- **leave_chat(chat_id)**: Leave a group or channel
|
||||||
|
- **get_participants(chat_id)**: List all participants
|
||||||
|
- **get_admins(chat_id)**: List all admins
|
||||||
|
- **get_banned_users(chat_id)**: List all banned users
|
||||||
|
- **promote_admin(chat_id, user_id)**: Promote user to admin
|
||||||
|
- **demote_admin(chat_id, user_id)**: Demote admin to user
|
||||||
|
- **ban_user(chat_id, user_id)**: Ban user
|
||||||
|
- **unban_user(chat_id, user_id)**: Unban user
|
||||||
|
- **get_invite_link(chat_id)**: Get invite link
|
||||||
|
- **export_chat_invite(chat_id)**: Export invite link
|
||||||
|
- **import_chat_invite(hash)**: Join chat by invite hash
|
||||||
|
- **join_chat_by_link(link)**: Join chat by invite link
|
||||||
|
|
||||||
### Messaging
|
### Messaging
|
||||||
- **get_messages** - Get messages from a specific chat with pagination
|
- **get_messages(chat_id, page, page_size)**: Paginated messages
|
||||||
- **list_messages** - Retrieve messages with powerful filtering (text search, date ranges)
|
- **list_messages(chat_id, limit, search_query, from_date, to_date)**: Filtered messages
|
||||||
- **send_message** - Send messages to any chat
|
- **send_message(chat_id, message)**: Send a message
|
||||||
- **get_message_context** - View the context around a specific message
|
- **reply_to_message(chat_id, message_id, text)**: Reply to a message
|
||||||
|
- **edit_message(chat_id, message_id, new_text)**: Edit your message
|
||||||
|
- **delete_message(chat_id, message_id)**: Delete a message
|
||||||
|
- **forward_message(from_chat_id, message_id, to_chat_id)**: Forward a message
|
||||||
|
- **pin_message(chat_id, message_id)**: Pin a message
|
||||||
|
- **unpin_message(chat_id, message_id)**: Unpin a message
|
||||||
|
- **mark_as_read(chat_id)**: Mark all as read
|
||||||
|
- **get_message_context(chat_id, message_id, context_size)**: Context around a message
|
||||||
|
- **get_history(chat_id, limit)**: Full chat history
|
||||||
|
- **get_pinned_messages(chat_id)**: List pinned messages
|
||||||
|
|
||||||
### Contact Management
|
### Contact Management
|
||||||
- **search_contacts** - Find contacts by name, username or phone number
|
- **list_contacts()**: List all contacts
|
||||||
- **get_direct_chat_by_contact** - Find personal chats with specific contacts
|
- **search_contacts(query)**: Search contacts
|
||||||
- **get_contact_chats** - List all chats (including groups) involving a contact
|
- **add_contact(phone, first_name, last_name)**: Add a contact
|
||||||
- **get_last_interaction** - View your most recent exchanges with a contact
|
- **delete_contact(user_id)**: Delete a contact
|
||||||
|
- **block_user(user_id)**: Block a user
|
||||||
|
- **unblock_user(user_id)**: Unblock a user
|
||||||
|
- **import_contacts(contacts)**: Bulk import contacts
|
||||||
|
- **export_contacts()**: Export all contacts as JSON
|
||||||
|
- **get_blocked_users()**: List blocked users
|
||||||
|
- **get_contact_ids()**: List all contact IDs
|
||||||
|
- **get_direct_chat_by_contact(contact_query)**: Find direct chat with a contact
|
||||||
|
- **get_contact_chats(contact_id)**: List all chats with a contact
|
||||||
|
- **get_last_interaction(contact_id)**: Most recent message with a contact
|
||||||
|
|
||||||
|
### User & Profile
|
||||||
|
- **get_me()**: Get your user info
|
||||||
|
- **update_profile(first_name, last_name, about)**: Update your profile
|
||||||
|
- **set_profile_photo(file_path)**: Set your profile photo
|
||||||
|
- **delete_profile_photo()**: Remove your profile photo
|
||||||
|
- **get_user_photos(user_id, limit)**: Get a user's profile photos
|
||||||
|
- **get_user_status(user_id)**: Get a user's online status
|
||||||
|
|
||||||
|
### Media
|
||||||
|
- **send_file(chat_id, file_path, caption)**: Send a file
|
||||||
|
- **send_voice(chat_id, file_path)**: Send a voice message
|
||||||
|
- **download_media(chat_id, message_id, file_path)**: Download media
|
||||||
|
- **upload_file(file_path)**: Upload a file to Telegram servers
|
||||||
|
- **get_media_info(chat_id, message_id)**: Get info about media in a message
|
||||||
|
|
||||||
|
### Search & Discovery
|
||||||
|
- **search_public_chats(query)**: Search public chats/channels/bots
|
||||||
|
- **search_messages(chat_id, query, limit)**: Search messages in a chat
|
||||||
|
- **resolve_username(username)**: Resolve a username to ID
|
||||||
|
|
||||||
|
### Stickers, GIFs, Bots
|
||||||
|
- **get_sticker_sets()**: List sticker sets
|
||||||
|
- **send_sticker(chat_id, file_path)**: Send a sticker
|
||||||
|
- **get_gif_search(query, limit)**: Search for GIFs
|
||||||
|
- **send_gif(chat_id, gif_id)**: Send a GIF
|
||||||
|
- **get_bot_info(bot_username)**: Get info about a bot
|
||||||
|
- **set_bot_commands(bot_username, commands)**: Set bot commands
|
||||||
|
|
||||||
|
### Privacy, Settings, and Misc
|
||||||
|
- **get_privacy_settings()**: Get privacy settings
|
||||||
|
- **set_privacy_settings(key, allow_users, disallow_users)**: Set privacy settings
|
||||||
|
- **mute_chat(chat_id)**: Mute notifications
|
||||||
|
- **unmute_chat(chat_id)**: Unmute notifications
|
||||||
|
- **archive_chat(chat_id)**: Archive a chat
|
||||||
|
- **unarchive_chat(chat_id)**: Unarchive a chat
|
||||||
|
- **get_recent_actions(chat_id)**: Get recent admin actions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 📋 Requirements
|
## 📋 Requirements
|
||||||
|
|
||||||
- Python 3.10+
|
- Python 3.10+
|
||||||
- [Telethon](https://docs.telethon.dev/) for Telegram API access
|
- [Telethon](https://docs.telethon.dev/)
|
||||||
- [MCP Python SDK](https://modelcontextprotocol.io/docs/)
|
- [MCP Python SDK](https://modelcontextprotocol.io/docs/)
|
||||||
- [UV](https://astral.sh/uv/) package manager
|
- [Claude Desktop](https://claude.ai/desktop) or [Cursor](https://cursor.so/) (or any MCP client)
|
||||||
- [Claude Desktop](https://claude.ai/desktop) app
|
|
||||||
|
|
||||||
## 🔧 Installation
|
---
|
||||||
|
|
||||||
### 1. Clone the Repository
|
## 🔧 Installation & Setup
|
||||||
|
|
||||||
|
### 1. Fork & Clone
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/l1v0n1/telegram-mcp-server
|
git clone https://github.com/chigwell/telegram-mcp.git
|
||||||
cd telegram-mcp-server
|
cd telegram-mcp
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. Generate Session String
|
### 2. Create a Virtual Environment
|
||||||
|
|
||||||
For better security and portability, this project uses Telethon's StringSession. Generate your session string:
|
```bash
|
||||||
|
python3 -m venv .venv
|
||||||
|
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
||||||
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Generate a Session String
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python session_string_generator.py
|
python session_string_generator.py
|
||||||
```
|
```
|
||||||
|
Follow the prompts to authenticate and update your `.env` file.
|
||||||
|
|
||||||
This will:
|
### 4. Configure .env
|
||||||
1. Ask for your phone number
|
|
||||||
2. Send a verification code to your Telegram app
|
|
||||||
3. Generate a session string and add it to your `.env` file
|
|
||||||
|
|
||||||
The session string allows authentication without storing SQLite session files, which helps avoid database lock issues and improves portability.
|
|
||||||
|
|
||||||
### 3. Set Up Your Environment
|
|
||||||
|
|
||||||
Create a `.env` file with your Telegram credentials:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
TELEGRAM_API_ID=your_api_id_here
|
TELEGRAM_API_ID=your_api_id_here
|
||||||
|
|
@ -70,89 +144,104 @@ TELEGRAM_API_HASH=your_api_hash_here
|
||||||
TELEGRAM_SESSION_NAME=anon
|
TELEGRAM_SESSION_NAME=anon
|
||||||
TELEGRAM_SESSION_STRING=your_session_string_here
|
TELEGRAM_SESSION_STRING=your_session_string_here
|
||||||
```
|
```
|
||||||
|
Get your API credentials at [my.telegram.org/apps](https://my.telegram.org/apps).
|
||||||
|
|
||||||
You can obtain API credentials at [my.telegram.org/apps](https://my.telegram.org/apps).
|
---
|
||||||
|
|
||||||
### 4. Install Dependencies
|
## ⚙️ Configuration for Claude & Cursor
|
||||||
|
|
||||||
```bash
|
### Claude Desktop
|
||||||
uv venv
|
Edit your Claude config (e.g. `~/Library/Application Support/Claude/claude_desktop_config.json`):
|
||||||
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
|
||||||
uv add "mcp[cli]" telethon python-dotenv nest_asyncio
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5. Configure Claude Desktop
|
|
||||||
|
|
||||||
#### On macOS/Linux:
|
|
||||||
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"mcpServers": {
|
"mcpServers": {
|
||||||
"telegram-mcp": {
|
"telegram-mcp": {
|
||||||
"command": "/full/path/to/uv",
|
"command": "/full/path/to/.venv/bin/python",
|
||||||
"args": [
|
"args": ["main.py"],
|
||||||
"--directory",
|
"cwd": "/full/path/to/telegram-mcp-server"
|
||||||
"/full/path/to/telegram-mcp-server",
|
|
||||||
"run",
|
|
||||||
"main.py"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
#### On Windows:
|
### Cursor
|
||||||
Edit `%APPDATA%\Claude\claude_desktop_config.json` with similar configuration.
|
Edit `~/.cursor/mcp.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"telegram-mcp": {
|
||||||
|
"command": "/full/path/to/.venv/bin/python",
|
||||||
|
"args": ["main.py"],
|
||||||
|
"cwd": "/full/path/to/telegram-mcp-server"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 🎮 Usage Examples
|
## 🎮 Usage Examples
|
||||||
|
|
||||||
Here are some ways to interact with Telegram through Claude:
|
- "Show my recent chats"
|
||||||
|
- "Send 'Hello world' to chat 123456789"
|
||||||
|
- "Add contact with phone +1234567890, name John Doe"
|
||||||
|
- "Create a group 'Project Team' with users 111, 222, 333"
|
||||||
|
- "Download the media from message 42 in chat 123456789"
|
||||||
|
- "Mute notifications for chat 123456789"
|
||||||
|
- "Promote user 111 to admin in group 123456789"
|
||||||
|
- "Search for public channels about 'news'"
|
||||||
|
|
||||||
### Basic Chat Navigation
|
You can use these tools via natural language in Claude, Cursor, or any MCP-compatible client.
|
||||||
- "Show me my most recent chats"
|
|
||||||
- "List my group chats with unread messages"
|
|
||||||
- "Show detailed information about chat 123456789"
|
|
||||||
|
|
||||||
### Messaging
|
---
|
||||||
- "Show me the last 10 messages from chat 123456789"
|
|
||||||
- "Send 'I'll be there in 10 minutes' to chat 123456789"
|
|
||||||
- "Find messages containing 'meeting' in chat 123456789"
|
|
||||||
- "Show messages from March 1-15, 2023 in chat 123456789"
|
|
||||||
|
|
||||||
### Contact Interactions
|
## 🛠️ Contribution Guide
|
||||||
- "Search for contacts named 'Alex'"
|
|
||||||
- "Find my direct chat with John"
|
|
||||||
- "Show all chats where I interact with contact 987654321"
|
|
||||||
- "Show my last conversation with Lisa"
|
|
||||||
|
|
||||||
### Advanced Features
|
1. **Fork this repo:** [chigwell/telegram-mcp](https://github.com/chigwell/telegram-mcp)
|
||||||
- "Show the context around message 42 in chat 123456789"
|
2. **Clone your fork:**
|
||||||
- "List all channels I'm subscribed to"
|
```bash
|
||||||
|
git clone https://github.com/<your-github-username>/telegram-mcp.git
|
||||||
|
```
|
||||||
|
3. **Create a new branch:**
|
||||||
|
```bash
|
||||||
|
git checkout -b my-feature
|
||||||
|
```
|
||||||
|
4. **Make your changes, add tests/docs if needed.**
|
||||||
|
5. **Push and open a Pull Request** to [chigwell/telegram-mcp](https://github.com/chigwell/telegram-mcp) with a clear description.
|
||||||
|
6. **Tag @l1v0n1** in your PR for review.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 🔒 Security Considerations
|
## 🔒 Security Considerations
|
||||||
|
- **Never commit your `.env` or session string.**
|
||||||
|
- The session string gives full access to your Telegram account—keep it safe!
|
||||||
|
- All processing is local; no data is sent anywhere except Telegram's API.
|
||||||
|
|
||||||
- **Private API Keys**: Never commit your `.env` file or session files to Git repositories
|
---
|
||||||
- **Session String**: The session string in your `.env` file provides full access to your Telegram account. Keep it secure.
|
|
||||||
- **Local Processing**: All Telegram data is processed locally on your machine - no data is sent to external servers beyond Telegram's own API.
|
|
||||||
- **Permissions**: The MCP server has the same access to Telegram as you would have with the official app, including reading and sending messages.
|
|
||||||
|
|
||||||
## 🛠️ Troubleshooting
|
## 🛠️ Troubleshooting
|
||||||
|
- **Check logs** in your MCP client (Claude/Cursor) and the terminal for errors.
|
||||||
|
- **Interpreter errors?** Make sure your `.venv` is created and selected.
|
||||||
|
- **Database lock?** Use session string authentication, not file-based sessions.
|
||||||
|
- **iCloud/Dropbox issues?** Move your project to a local path without spaces if you see odd errors.
|
||||||
|
- **Regenerate session string** if you change your Telegram password or see auth errors.
|
||||||
|
|
||||||
If you encounter issues:
|
---
|
||||||
|
|
||||||
1. Check Claude Desktop logs for error messages
|
|
||||||
2. Ensure your Telegram API credentials are correct
|
|
||||||
3. Verify that the paths in your Claude Desktop config are absolute and correct
|
|
||||||
4. If you see database lock errors, use the session string authentication method
|
|
||||||
5. If you need to regenerate your session string, run `python session_string_generator.py` again
|
|
||||||
|
|
||||||
## 📄 License
|
## 📄 License
|
||||||
|
|
||||||
This project is licensed under the [Apache 2.0 License](LICENSE).
|
This project is licensed under the [Apache 2.0 License](LICENSE).
|
||||||
|
|
||||||
## 🙏 Acknowledgements
|
---
|
||||||
|
|
||||||
- [Telethon](https://github.com/LonamiWebs/Telethon) for the Telegram client library
|
## 🙏 Acknowledgements
|
||||||
- [Model Context Protocol](https://modelcontextprotocol.io/) for the integration framework
|
- [Telethon](https://github.com/LonamiWebs/Telethon)
|
||||||
- [Anthropic](https://www.anthropic.com/) for Claude and the Claude Desktop app
|
- [Model Context Protocol](https://modelcontextprotocol.io/)
|
||||||
|
- [Claude](https://www.anthropic.com/) and [Cursor](https://cursor.so/)
|
||||||
|
- [chigwell/telegram-mcp](https://github.com/chigwell/telegram-mcp) (upstream)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Maintained by [l1v0n1](https://github.com/l1v0n1). PRs welcome!**
|
||||||
|
|
@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
||||||
|
|
||||||
[project]
|
[project]
|
||||||
name = "telegram-mcp"
|
name = "telegram-mcp"
|
||||||
version = "1.5.0"
|
version = "2.0.0"
|
||||||
description = "Telegram integration for Claude via the Model Context Protocol"
|
description = "Telegram integration for Claude via the Model Context Protocol"
|
||||||
readme = "README.md"
|
readme = "README.md"
|
||||||
authors = [
|
authors = [
|
||||||
|
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 170 KiB After Width: | Height: | Size: 306 KiB |
2
uv.lock
2
uv.lock
|
|
@ -405,7 +405,7 @@ wheels = [
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "telegram-mcp"
|
name = "telegram-mcp"
|
||||||
version = "1.5.0"
|
version = "2.0.0"
|
||||||
source = { editable = "." }
|
source = { editable = "." }
|
||||||
dependencies = [
|
dependencies = [
|
||||||
{ name = "dotenv" },
|
{ name = "dotenv" },
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue