Telegram MCP Server

Instructions

Implementation Reference

• src/server.ts:544-593 (handler)

  The primary handler function for the 'telegram_login' tool. It extracts the optional phone_number from arguments, calls the TelegramAuth.login() method, and returns a formatted success or error response.
  private async handleTelegramLogin(args: any): Promise<any> { const phoneNumber = args.phone_number; try { const success = await this.auth.login(phoneNumber); if (success) { return { content: [ { type: 'text', text: `✅ Successfully authenticated with Telegram! You can now use the authenticated scraping tools to access restricted content. Use 'scrape_channel_authenticated' to scrape channels with full access.` } ] }; } else { return { content: [ { type: 'text', text: `❌ Authentication failed. Please try again. Make sure to: 1. Complete the login process in the browser window 2. Enter the verification code if prompted 3. Allow sufficient time for the login to complete` } ] }; } } catch (error) { return { content: [ { type: 'text', text: `❌ Login error: ${error instanceof Error ? error.message : 'Unknown error'} Please check: - Chrome is installed and accessible - You have a stable internet connection - The phone number is in international format (if provided)` } ] }; } }
• src/server.ts:221-234 (registration)

  Registration of the 'telegram_login' tool in the server's tool list, including its description and input schema definition.
  { name: 'telegram_login', description: 'Authenticate with Telegram Web to access restricted content', inputSchema: { type: 'object', properties: { phone_number: { type: 'string', description: 'Phone number in international format (optional, for automated login)' } }, required: [] } },
• src/auth/telegram-auth.ts:15-180 (helper)

  Core helper method implementing the Telegram Web login logic using Puppeteer: launches browser, navigates to web.telegram.org, handles manual or phone-based login, detects success, and saves authentication cookies.
  async login(phoneNumber?: string): Promise<boolean> { let browser: Browser | null = null; let page: Page | null = null; try { logger.info('Starting Telegram Web authentication...'); // Launch browser in non-headless mode for login browser = await this.browserManager.launch(false); page = await browser.newPage(); // Set viewport await page.setViewport({ width: 1280, height: 800 }); // Set longer default timeout for login process page.setDefaultTimeout(120000); // 2 minutes // Navigate to Telegram Web - try different URLs logger.info('Navigating to Telegram Web...'); // Try the regular version first (might use cookies) try { await page.goto('https://web.telegram.org/a/', { waitUntil: 'networkidle2', timeout: 60000 }); logger.info('Loaded Telegram Web A version'); } catch { // Fallback to Z version try { logger.info('Trying Telegram Web Z version...'); await page.goto('https://web.telegram.org/z/', { waitUntil: 'networkidle2', timeout: 60000 }); logger.info('Loaded Telegram Web Z version'); } catch { // Final fallback to K version logger.info('Trying Telegram Web K version...'); await page.goto('https://web.telegram.org/k/', { waitUntil: 'networkidle2', timeout: 60000 }); logger.info('Loaded Telegram Web K version'); } } // Wait a bit for the page to settle await new Promise(resolve => setTimeout(resolve, 2000)); // Check if already logged in const isLoggedIn = await this.checkIfLoggedIn(page); if (isLoggedIn) { logger.info('Already logged in! Saving cookies...'); await this.cookieManager.saveCookies(page); await new Promise(resolve => setTimeout(resolve, 3000)); return true; } // Wait for login form with more specific selectors logger.info('Waiting for login form...'); try { await page.waitForSelector('canvas#qr-canvas, .input-wrapper, .login-container, .qr-container', { timeout: 30000 }); logger.info('Login form found'); } catch { logger.warn('Could not find login form selectors, continuing anyway...'); } // Handle phone number input if (phoneNumber) { logger.info('Entering phone number...'); await this.enterPhoneNumber(page, phoneNumber); } else { logger.info('='.repeat(60)); logger.info('MANUAL LOGIN REQUIRED'); logger.info('Please complete login in the browser window:'); logger.info('1. Scan the QR code with your mobile Telegram app'); logger.info('2. OR click "Log in by phone number" and enter your details'); logger.info('3. Complete any verification steps'); logger.info('='.repeat(60)); } // Wait for successful login with periodic checks logger.info('Waiting for login completion (this may take a few minutes)...'); const loginSuccess = await this.waitForLoginWithProgress(page); if (loginSuccess) { logger.info('Login detected! Waiting for page to fully load...'); // Give more time for all resources to load await new Promise(resolve => setTimeout(resolve, 5000)); // Try to navigate to a channel to ensure session is established try { logger.info('Testing session by navigating to a channel...'); const currentUrl = page.url(); // Determine which version we're using and navigate accordingly if (currentUrl.includes('/a/')) { await page.goto('https://web.telegram.org/a/#@durov', { waitUntil: 'networkidle2', timeout: 30000 }); } else if (currentUrl.includes('/z/')) { await page.goto('https://web.telegram.org/z/#@durov', { waitUntil: 'networkidle2', timeout: 30000 }); } else { await page.goto('https://web.telegram.org/k/#@durov', { waitUntil: 'networkidle2', timeout: 30000 }); } await new Promise(resolve => setTimeout(resolve, 3000)); // Navigate back to main page await page.goto(currentUrl, { waitUntil: 'networkidle2', timeout: 30000 }); await new Promise(resolve => setTimeout(resolve, 2000)); } catch { logger.warn('Could not navigate to test channel, continuing anyway...'); } logger.info('Saving authentication data...'); await this.cookieManager.saveCookies(page); // For Telegram Web K, we can't rely on traditional cookie verification // The auth is stored in IndexedDB which we can't easily access logger.info('✅ Authentication data saved!'); logger.info('Note: Telegram Web K uses IndexedDB for auth, not cookies.'); logger.info('The authentication should work even if no cookies were found.'); // Keep browser open a bit longer await new Promise(resolve => setTimeout(resolve, 5000)); return true; } else { logger.error('Login timeout - no login detected within time limit'); return false; } } catch (error) { logger.error('Authentication error:', error); // Log more details about the error if (error instanceof Error) { logger.error('Error details:', error.message); logger.error('Stack trace:', error.stack); } return false; } finally { // Don't close immediately - give user time to see any errors if (page || browser) { logger.info('Closing browser in 5 seconds...'); await new Promise(resolve => setTimeout(resolve, 5000)); } if (page) await page.close(); if (browser) await browser.close(); } }