Skip to main content
Glama

Telegram MCP Server

by DLHellMe
MIT License
6
5
  • Apple
  • Linux

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

  • 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:
git clone https://github.com/DLHellMe/telegram-mcp-server.git cd telegram-mcp-server
  1. Install dependencies:
npm install
  1. Copy the example environment file:
cp .env.example .env
  1. 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
  2. Build the project:
npm run build

🔧 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

{ "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.

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

  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:

⚠️ 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

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/DLHellMe/telegram-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server