Telegram MCP Server

Instructions

Implementation Reference

• src/server.ts:272-290 (registration)

  Registration of the 'scrape_manual' tool in getTools(), including name, description, and input schema definition.

  {
    name: 'scrape_manual',
    description: 'Manual scraping mode: Opens browser for you to login and navigate to any channel, then scrapes it',
    inputSchema: {
      type: 'object',
      properties: {
        limit: {
          type: 'number',
          description: 'Maximum number of posts to scrape (optional)'
        },
        save_to_file: {
          type: 'boolean',
          description: 'Save results to MD and JSON files',
          default: true
        }
      },
      required: []
    }
  },

• src/server.ts:275-290 (schema)

  Input schema definition for the 'scrape_manual' tool.

    inputSchema: {
      type: 'object',
      properties: {
        limit: {
          type: 'number',
          description: 'Maximum number of posts to scrape (optional)'
        },
        save_to_file: {
          type: 'boolean',
          description: 'Save results to MD and JSON files',
          default: true
        }
      },
      required: []
    }
  },

• src/server.ts:678-761 (handler)

  The primary handler function for the 'scrape_manual' tool. It dynamically imports ManualTelegramScraper, launches a browser for manual user navigation and login, performs the scrape, optionally saves results to files, and returns a formatted response with a sample.

    private async handleManualScrape(args: any): Promise<any> {
      try {
        logger.info('Starting manual scrape mode...');
        
        // Import manual scraper and required modules
        const { ManualTelegramScraper } = await import('./scraper/manual-scraper.js');
        const { join } = await import('path');
        const { writeFile, mkdir } = await import('fs/promises');
        
        const manualScraper = new ManualTelegramScraper();
        
        // Open browser and wait for user to navigate
        const { browser, page } = await manualScraper.loginAndWaitForChannel();
        
        // Scrape the current channel
        const options = {
          maxPosts: args.limit || args.max_posts || 0
        };
        
        const result = await manualScraper.scrapeCurrentChannel(page, options);
        
        // Save to file
        if (args.save_to_file !== false) {
          const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
          const filename = `${result.channel.username}_${timestamp}_manual.md`;
          
          const formatter = new MarkdownFormatter();
          const markdown = formatter.format(result);
          
          const basePath = 'C:\\Users\\User\\AppData\\Roaming\\Claude\\telegram_scraped_data';
          const filepath = join(basePath, filename);
          
          await mkdir(basePath, { recursive: true });
          await writeFile(filepath, markdown, 'utf8');
          
          // Also save JSON
          const jsonFilename = `${result.channel.username}_${timestamp}_manual.json`;
          const jsonFilepath = join(basePath, jsonFilename);
          await writeFile(jsonFilepath, JSON.stringify(result, null, 2), 'utf8');
          
          logger.info(`Saved to: ${filepath}`);
        }
        
        // Close browser
        await manualScraper.close(browser);
        
        // Format response
        const summary = result.posts.slice(0, 5).map(post => ({
          date: post.date.toISOString(),
          content: post.content.substring(0, 100) + (post.content.length > 100 ? '...' : ''),
          views: post.views
        }));
        
        return {
          content: [
            {
              type: 'text',
              text: `✅ Successfully scraped ${result.posts.length} posts from ${result.channel.name}
  
  Channel: @${result.channel.username}
  Total posts scraped: ${result.posts.length}
  
  ${args.save_to_file !== false ? `Files saved to:
  - Markdown: C:\\Users\\User\\AppData\\Roaming\\Claude\\telegram_scraped_data\\${result.channel.username}_*_manual.md
  - JSON: C:\\Users\\User\\AppData\\Roaming\\Claude\\telegram_scraped_data\\${result.channel.username}_*_manual.json
  
  ` : ''}Sample of first 5 posts:
  ${summary.map(post => `\n📅 ${post.date}\n${post.content}\n👁 ${post.views} views`).join('\n---\n')}`
            }
          ]
        };
        
      } catch (error) {
        logger.error('Manual scrape failed:', error);
        return {
          content: [
            {
              type: 'text',
              text: `❌ Manual scrape failed: ${error instanceof Error ? error.message : 'Unknown error'}`
            }
          ]
        };
      }
    }

• src/scraper/manual-scraper.ts:8-206 (helper)

  Helper class ManualTelegramScraper providing the core implementation for manual scraping: browser launch, user-guided navigation, channel scraping via scrolling and parsing, post collection, and cleanup.

  export class ManualTelegramScraper {
    private browserManager: BrowserManager;
    private cookieManager: CookieManager;
  
    constructor() {
      this.browserManager = new BrowserManager();
      this.cookieManager = new CookieManager();
    }
  
    async loginAndWaitForChannel(): Promise<{ browser: Browser; page: Page }> {
      logger.info('Opening browser for manual login and navigation...');
      
      // Launch browser in non-headless mode
      const browser = await this.browserManager.launch(false);
      const page = await browser.newPage();
      
      // Set viewport
      await page.setViewport({ width: 1280, height: 800 });
      
      // Load cookies if available
      await this.cookieManager.loadCookies(page);
      
      // Navigate to Telegram Web
      logger.info('Navigating to Telegram Web...');
      await page.goto('https://web.telegram.org/a/', {
        waitUntil: 'networkidle2',
        timeout: 60000
      });
      
      // Instructions for user
      logger.info('='.repeat(60));
      logger.info('MANUAL NAVIGATION REQUIRED');
      logger.info('1. Log in to Telegram if needed');
      logger.info('2. Navigate to the channel you want to scrape');
      logger.info('3. Make sure the channel messages are visible');
      logger.info('4. Press Enter here when ready to start scraping');
      logger.info('='.repeat(60));
      
      // Wait for user to press Enter
      await new Promise<void>(resolve => {
        process.stdin.once('data', () => {
          resolve();
        });
      });
      
      // Save cookies for future use
      await this.cookieManager.saveCookies(page);
      
      return { browser, page };
    }
  
    async scrapeCurrentChannel(page: Page, options: Partial<ScrapeOptions> = {}): Promise<ScrapeResult> {
      logger.info('Starting to scrape current channel...');
      
      try {
        // Get current URL to extract channel info
        const currentUrl = page.url();
        logger.info(`Current URL: ${currentUrl}`);
        
        // Get channel info from the page
        const channelHtml = await page.content();
        const parser = new DataParser(channelHtml);
        let channel = parser.parseChannelInfo();
        
        // Try to extract channel name from URL or page title
        if (channel.name === 'Unknown Channel') {
          const pageTitle = await page.title();
          if (pageTitle && pageTitle !== 'Telegram') {
            channel.name = pageTitle;
          }
        }
        
        // Extract username from URL if possible
        const urlMatch = currentUrl.match(/#@?([^/?]+)$/);
        if (urlMatch && urlMatch[1] && channel.username === 'unknown') {
          channel.username = urlMatch[1].replace('-', '');
        }
        
        logger.info(`Scraping channel: ${channel.name} (@${channel.username})`);
        
        // Scroll and collect posts
        const posts = await this.scrollAndCollectPosts(page, options);
        
        logger.info(`Scraping complete. Total posts: ${posts.length}`);
        
        return {
          channel,
          posts,
          scrapedAt: new Date(),
          totalPosts: posts.length
        };
        
      } catch (error) {
        logger.error('Scraping failed:', error);
        return {
          channel: {
            name: 'Unknown',
            username: 'unknown',
            description: ''
          },
          posts: [],
          scrapedAt: new Date(),
          totalPosts: 0,
          error: error instanceof Error ? error.message : 'Unknown error'
        };
      }
    }
  
    private async scrollAndCollectPosts(page: Page, options: Partial<ScrapeOptions>): Promise<any[]> {
      logger.info('Starting to scroll and collect posts');
      
      const posts: Map<string, any> = new Map();
      let scrollAttempts = 0;
      let lastPostCount = 0;
      let noNewPostsCount = 0;
      const maxScrollAttempts = options.maxPosts ? Math.min(50, Math.ceil(options.maxPosts / 20)) : 50;
      
      while (scrollAttempts < maxScrollAttempts) {
        // Parse current posts
        const html = await page.content();
        const parser = new DataParser(html);
        const currentPosts = parser.parsePosts();
        
        // Add new posts to map (deduplication)
        for (const post of currentPosts) {
          if (!posts.has(post.id)) {
            posts.set(post.id, post);
            
            // Log progress
            if (posts.size % 20 === 0) {
              logger.info(`Collected ${posts.size} posts so far...`);
            }
          }
        }
        
        // Check if we've reached max posts
        if (options.maxPosts && posts.size >= options.maxPosts) {
          logger.info(`Reached maxPosts limit: ${options.maxPosts}`);
          break;
        }
        
        // Check if we're getting new posts
        if (posts.size === lastPostCount) {
          noNewPostsCount++;
          if (noNewPostsCount >= 3) {
            logger.info('No new posts found after 3 attempts, stopping');
            break;
          }
        } else {
          noNewPostsCount = 0;
          lastPostCount = posts.size;
        }
        
        // Scroll to load more messages
        await this.scrollUp(page);
        
        // Wait for new content
        await new Promise(resolve => setTimeout(resolve, 2000));
        
        scrollAttempts++;
      }
      
      logger.info(`Scrolling complete. Total posts collected: ${posts.size}`);
      
      // Sort posts by date (newest first) and limit if needed
      let sortedPosts = Array.from(posts.values()).sort((a, b) => b.date.getTime() - a.date.getTime());
      
      if (options.maxPosts && sortedPosts.length > options.maxPosts) {
        sortedPosts = sortedPosts.slice(0, options.maxPosts);
      }
      
      return sortedPosts;
    }
  
    private async scrollUp(page: Page): Promise<void> {
      // Scroll within the messages container to load older messages
      await page.evaluate(() => {
        const container = document.querySelector('.bubbles-inner, .messages-container, .bubbles, .im_history_scrollable');
        if (container) {
          // Scroll to top of the container to load older messages
          container.scrollTop = 0;
        } else {
          // Try to find any scrollable container
          const scrollables = document.querySelectorAll('[class*="scroll"], [class*="messages"], [class*="chat"]');
          for (let i = 0; i < scrollables.length; i++) {
            const el = scrollables[i] as HTMLElement;
            if (el.scrollHeight > el.clientHeight) {
              el.scrollTop = 0;
              break;
            }
          }
        }
      });
    }
  
    async close(browser: Browser): Promise<void> {
      await browser.close();
    }
  }