Telegram MCP Server

Instructions

Implementation Reference

• src/server.ts:623-676 (handler)

  Core handler function for the 'scrape_channel_authenticated' tool. Verifies user authentication, configures scrape options, executes scrape using authenticated scraper instance, formats results to markdown, and returns structured response with error handling.

    private async handleScrapeChannelAuthenticated(args: any): Promise<any> {
      // Check authentication first
      const isAuthenticated = await this.auth.isAuthenticated();
      if (!isAuthenticated) {
        return {
          content: [
            {
              type: 'text',
              text: '❌ Not authenticated. Please use telegram_login first to access restricted content.'
            }
          ]
        };
      }
  
      const options: ScrapeOptions = {
        url: args.url,
        maxPosts: args.max_posts || 100,
        includeReactions: true
      };
  
      try {
        const result = await this.authScraper.scrape(options);
        const markdown = this.formatter.format(result);
  
        return {
          content: [
            {
              type: 'text',
              text: `# Authenticated Scrape Results
  
  ${markdown}
  
  ✅ Scraped using authenticated session - restricted content should be accessible.`
            }
          ]
        };
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: `❌ Authenticated scrape failed: ${error instanceof Error ? error.message : 'Unknown error'}
  
  This might happen if:
  - The authentication session expired
  - The channel requires additional permissions
  - There was a network error
  
  Try running telegram_login again if the problem persists.`
            }
          ]
        };
      }
    }

• src/server.ts:253-271 (registration)

  Tool registration entry in getTools() method, defining name, description, and input schema for the scrape_channel_authenticated tool.

  {
    name: 'scrape_channel_authenticated',
    description: 'Scrape a Telegram channel using authenticated session (can access restricted content)',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'The Telegram channel URL (e.g., https://t.me/channelname)'
        },
        max_posts: {
          type: 'number',
          description: 'Maximum number of posts to scrape (default: 100)',
          default: 100
        }
      },
      required: ['url']
    }
  },

• src/server.ts:89-90 (registration)

  Switch case in tool call handler that routes calls to the specific handler function.

  case 'scrape_channel_authenticated':
    return await this.handleScrapeChannelAuthenticated(args);