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)

   Use telegram_api_login to connect to Telegram

2. api_scrape_channel - Scrape channel posts (unlimited by default)

   Use api_scrape_channel with url="https://t.me/channelname"

   Or with a limit:

   Use api_scrape_channel with url="https://t.me/channelname" and max_posts=50

3. api_search_channel - Search within a channel

   Use api_search_channel with url="https://t.me/channelname" and query="keyword"

Web Scraping Tools

1. scrape_channel - Scrape public channels

   Use scrape_channel with url="https://t.me/channelname"

2. 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 - 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

3. Make your changes

4. 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