Enables access to Telegram channels and groups through both API and web scraping modes. Provides tools for logging in, retrieving posts from channels, searching within channels, and accessing private channels the user is a member of.
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
- Clone this repository:
- Install dependencies:
- Copy the example environment file:
- Edit
.env
and add your configuration:- For API mode: Add your
TELEGRAM_API_ID
andTELEGRAM_API_HASH
- For web scraping: Default settings work out of the box
- For API mode: Add your
- Build the project:
🔧 Configuration
Getting Telegram API Credentials
- Go to https://my.telegram.org
- Log in with your phone number
- Click "API development tools"
- Create a new application
- Copy your
api_id
andapi_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
- telegram_api_login - Authenticate with Telegram (first time only)
- api_scrape_channel - Scrape channel posts (unlimited by default)Or with a limit:
- api_search_channel - Search within a channel
Web Scraping Tools
- scrape_channel - Scrape public channels
- 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:
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
📄 License
MIT License - see LICENSE file for details
🙏 Acknowledgments
Built with:
- Model Context Protocol SDK
- GramJS - Telegram client library
- Puppeteer - Browser automation
⚠️ Disclaimer
This tool is for educational and research purposes. Please respect Telegram's Terms of Service and the privacy of channel members. Always obtain permission before scraping private channels.
🐛 Troubleshooting
API Mode Issues
- "Not connected to Telegram API": Run
telegram_api_login
first - Phone number format: Include country code (e.g., +1234567890)
- 2FA errors: Enter your 2FA password when prompted
Web Scraping Issues
- "No Chrome binary found": Install Chrome or Chromium
- Login issues: Ensure you're using the correct phone format
- Timeout errors: Increase
BROWSER_TIMEOUT
in.env
📞 Support
- Create an issue on GitHub for bugs
- Check existing issues before creating new ones
- Include error messages and logs when reporting issues
This server cannot be installed
A Model Context Protocol server that enables Claude to interact with Telegram channels and groups through both direct API access and web scraping methods.