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:
git clone https://github.com/DLHellMe/telegram-mcp-server.git
cd telegram-mcp-server
- Install dependencies:
- Copy the example environment file:
- 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
- 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 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
{
"mcpServers": {
"telegram-scraper": {
"command": "node",
"args": ["/absolute/path/to/telegram-mcp-server/dist/index.js"],
"env": {
"TELEGRAM_API_ID": "your_api_id",
"TELEGRAM_API_HASH": "your_api_hash"
}
}
}
}
📖 Usage
After configuration, restart Claude Desktop. The Telegram tools will be available in Claude.
- telegram_api_login - Authenticate with Telegram (first time only)
Use telegram_api_login to connect to Telegram
- api_scrape_channel - Scrape channel posts (unlimited by default)
Use api_scrape_channel with url="https://t.me/channelname"
Use api_scrape_channel with url="https://t.me/channelname" and max_posts=50
- api_search_channel - Search within a channel
Use api_search_channel with url="https://t.me/channelname" and query="keyword"
- scrape_channel - Scrape public channels
Use scrape_channel with url="https://t.me/channelname"
- telegram_login - Login for restricted content
Use telegram_login with phone="+1234567890"
🔒 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
# Run in development mode
npm run dev
# Build the project
npm run build
# Watch for changes
npm run watch
🤝 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:
⚠️ 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