telegram

This MCP server enables Claude to interact with Telegram channels and groups via two operational modes: API mode and web scraping mode. In API mode, the server communicates directly with Telegram using MTProto credentials to fetch complete message metadata (views, forwards, reactions) and to search within channels, including private channels you are a member of. This mode requires you to provide Telegram API credentials (API ID and API hash) and supports persistent sessions so you only authenticate once. In web scraping mode, the server uses headless browser automation to scrape publicly accessible Telegram content without API credentials. This is useful if you don’t have API access or need quick, anonymous access to public channels. Claude exposes tools for both modes via a consistent interface, enabling login, channel scraping, and channel search. Tools include telegram_api_login (authenticate for API mode), api_scrape_channel (fetch channel posts with optional limits), api_search_channel (search within a channel), and scrape_channel / telegram_login (web scraping workflow for restricted content).

To use, configure Claude to load the telegram server as a Claude MCP, providing the appropriate environment variables for the chosen mode. Then, select the desired tool in Claude’s Telegram suite to perform actions such as scraping posts, retrieving full metadata, or performing keyword searches within channels.

Prerequisites:

• Node.js 18.0.0 or higher
• npm (comes with Node.js)
• Chrome/Chromium for web scraping mode (optional if using API mode)
• Telegram API credentials (for API mode): API_ID and API_HASH

Installation steps:

1. Clone the repository:

git clone https://github.com/DLHellMe/telegram-mcp-server.git
cd telegram-mcp-server

2. Install dependencies:

npm install

3. Copy the example environment file and edit it with your credentials:

cp .env.example .env

4. Build the project (if a build step exists):

npm run build

5. Start the MCP server (adjust command if you use a different entry file or environment):

node dist/index.js

6. In Claude Desktop, add the MCP server configuration pointing to the running server (see mcp_config example).

Tips and notes:

• Never commit your .env file as it contains sensitive credentials.
• API credentials are user-specific; each user should provide their own API_ID and API_HASH.
• Session data and cookies are stored locally; you can override the storage path with TELEGRAM_DATA_PATH if needed.
• If you encounter API connection issues, run telegram_api_login first to establish a session.
• For web scraping, ensure Chrome/Chromium is installed and accessible to the scraper; network timeouts can be adjusted via BROWSER_TIMEOUT or environment settings.
• If using private channels, ensure your Telegram account is a member to access content in API mode.
• Check the README’s troubleshooting section for common API and scraping issues.