DLHellMe/telegram-mcp-server

A powerful MCP (Model Context Protocol) server that enables Claude to interact with Telegram channels and groups. This server provides both web scraping and direct API access to Telegram content.
🚀 Features
Version 0.3.0 - Dual Mode Operation
API Mode (Recommended) ⚡
- **100x faster** than web scraping
- Direct access via Telegram's MTProto protocol
- Search functionality within channels
- Access to private channels you're a member of
- Complete message metadata (views, reactions, forwards)
- Persistent sessions - authenticate once
- No browser automation needed
- **Unlimited post retrieval** by default
Web Scraping Mode 🌐
- No API credentials required
- Browser-based scraping with Puppeteer
- Authentication support for restricted content
- Visual media extraction
- Suitable for quick, anonymous access
📋 Prerequisites
- Node.js 18.0.0 or higher
- Chrome/Chromium (for web scraping mode)
- Telegram API credentials (for API mode) - Get them here
🛠️ Installation
1. Clone this repository:
2. Install dependencies:
3. Copy the example environment file:
4. Edit .env and add your configuration:
- For API mode: Add your TELEGRAM_API_ID and TELEGRAM_API_HASH
- For web scraping: Default settings work out of the box
5. Build the project:
🔧 Configuration
Getting Telegram API Credentials
1. Go to https://my.telegram.org
2. Log in with your phone number
3. Click "API development tools"
4. Create a new application
5. Copy your api_id and api_hash to the .env file
Claude Desktop Configuration
Add this to your Claude Desktop config file:
**Windows**: %APPDATA%\Claude\claude_desktop_config.json
**macOS**: ~/Library/Application Support/Claude/claude_desktop_config.json
**Linux**: ~/.config/Claude/claude_desktop_config.json
📖 Usage
After configuration, restart Claude Desktop. The Telegram tools will be available in Claude.
API Mode Tools
1. **telegram_api_login** - Authenticate with Telegram (first time only)
2. **api_scrape_channel** - Scrape channel posts (unlimited by default)
Or with a limit:
3. **api_search_channel** - Search within a channel
Web Scraping Tools
1. **scrape_channel** - Scrape public channels
2. **telegram_login** - Login for restricted content
🔒 Data Storage
Session data and cookies are stored in platform-specific directories:
- **Windows**: %APPDATA%\telegram-mcp-data
- **macOS**: ~/Library/Application Support/telegram-mcp-data
- **Linux**: ~/.config/telegram-mcp-data
You can override this with the TELEGRAM_DATA_PATH environment variable.
🛡️ Security Notes
- **Never commit your .env file** - it contains sensitive API credentials
- API credentials are personal - each user needs their own
- Session files contain authentication data - keep them secure
- Use the .gitignore file to prevent accidental commits
📝 Development
🤝 Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch