Instagram Engagement MCP

Instructions

Implementation Reference

• src/index.ts:428-528 (handler)

  The main execution function for the extract_demographics tool. Handles input validation, determines if input is post or account, fetches sample users (likers for posts, followers for accounts), performs basic demographic analysis (e.g., private/verified ratios), and returns results.
  private async handleExtractDemographics(args: ExtractDemographicsArgs) { console.error('[Tool] handleExtractDemographics called with args:', args); const { accountOrPostUrl, sampleSize = 50 } = args; // Determine if it's a post URL or username let targetId: string; let targetType: 'account' | 'post'; if (isValidPostUrl(accountOrPostUrl)) { targetType = 'post'; const mediaId = await this.getMediaIdFromUrl(accountOrPostUrl); if (!mediaId) { throw new McpError(ErrorCode.InvalidParams, 'Could not extract media ID from post URL.'); } targetId = mediaId; console.error(`[Tool] Extracting demographics from post: ${targetId}`); } else if (isValidUsername(accountOrPostUrl)) { targetType = 'account'; try { const userId = await this.ig.user.getIdByUsername(accountOrPostUrl); targetId = String(userId); // Convert number userId to string for targetId console.error(`[Tool] Extracting demographics from account followers: ${accountOrPostUrl} (ID: ${targetId})`); } catch(e: any) { if (e.name === 'IgNotFoundError') { throw new McpError(ErrorCode.InvalidParams, `Account ${accountOrPostUrl} not found.`); } throw new McpError(ErrorCode.InternalError, `Failed to get user ID for ${accountOrPostUrl}: ${e.message}`); } } else { throw new McpError(ErrorCode.InvalidParams, 'Invalid input. Provide a valid Instagram username or post URL.'); } try { let users: any[] = []; if (targetType === 'post') { // Get likers or commenters as sample console.error(`[Tool Debug] Attempting to fetch likers for media ID: ${targetId}`); const likersResponse = await this.ig.media.likers(targetId); let fetchedUsers: any[] = likersResponse.users || []; // Access users from the response object // Manual pagination simulation (if needed and possible, likers might not support feed pagination) // The private API might not offer easy pagination for likers beyond the initial batch. // For simplicity, we'll just use the first batch returned. /* let fetchedUsers: any[] = []; do { // Feed results are usually directly items const items = await likersFeed.items(); fetchedUsers = fetchedUsers.concat(items); if (fetchedUsers.length >= sampleSize) break; await new Promise(resolve => setTimeout(resolve, 200 + Math.random() * 300)); } while (likersFeed.isMoreAvailable()); */ users = fetchedUsers.slice(0, sampleSize); console.error(`[Tool] Fetched ${users.length} likers from post ${targetId}`); } else { // targetType === 'account' const userIdNum = parseInt(targetId, 10); const followersFeed = this.ig.feed.accountFollowers(userIdNum); let fetchedUsers: any[] = []; do { const items = await followersFeed.items(); fetchedUsers = fetchedUsers.concat(items); if (fetchedUsers.length >= sampleSize) break; await new Promise(resolve => setTimeout(resolve, 200 + Math.random() * 300)); } while (followersFeed.isMoreAvailable()); users = fetchedUsers.slice(0, sampleSize); console.error(`[Tool] Fetched ${users.length} followers from account ${accountOrPostUrl}`); } if (users.length === 0) { return { results: { message: 'No users found to analyze (post might have no likes/comments, or account has no followers/is private).', demographics: {} } }; } // Placeholder for actual demographic analysis const demographics = { sampleAnalyzed: users.length, commonLocationsGuess: ['Unknown'], genderDistributionGuess: { male: 0.4, female: 0.4, unknown: 0.2 }, accountTypes: { private: users.filter(u => u.is_private).length / users.length, verified: users.filter(u => u.is_verified).length / users.length, }, sampleUserProfiles: users.slice(0, 5).map(u => ({ username: u.username, fullName: u.full_name, isPrivate: u.is_private, })) }; return { results: { demographics } }; } catch (error: any) { console.error(`[API Error] Failed to extract demographics for ${accountOrPostUrl}:`, error.message || error); if (error.name === 'IgNotFoundError') { throw new McpError(ErrorCode.InvalidParams, `${targetType === 'post' ? 'Post' : 'Account'} not found or access denied.`); } throw new McpError(ErrorCode.InternalError, `Failed to fetch users for demographic analysis: ${error.message}`); } }
• src/index.ts:38-41 (schema)

  TypeScript interface defining the expected input parameters for the extract_demographics tool.
  interface ExtractDemographicsArgs { accountOrPostUrl: string; sampleSize?: number; }
• src/index.ts:172-189 (registration)

  Registration of the extract_demographics tool in the MCP ListTools handler, defining name, description, and JSON input schema.
  { name: 'extract_demographics', description: 'Extract demographic insights from users engaged with a post or account', inputSchema: { type: 'object', properties: { accountOrPostUrl: { type: 'string', description: 'Instagram account handle or post URL to analyze', }, sampleSize: { type: 'number', description: 'Number of users to sample for demographic analysis (default: 50)', }, }, required: ['accountOrPostUrl'], }, },
• src/index.ts:270-271 (registration)

  Dispatch case in the CallToolRequestSchema handler that routes calls to the extract_demographics handler function.
  case 'extract_demographics': return await this.handleExtractDemographics(args as unknown as ExtractDemographicsArgs);
• src/index.ts:777-824 (helper)

  Helper function to resolve Instagram post URLs to media IDs, crucial for handling post inputs in the demographics extraction.
  private async getMediaIdFromUrl(url: string): Promise<string | null> { try { // Extract shortcode first const shortcode = extractPostIdFromUrl(url); if (!shortcode) return null; // Getting the numeric media PK (required by many feed functions) from URL/shortcode is unreliable. // Option 1: Use a library method if exists (e.g., getIdFromUrl - hypothetical) // Option 2: Use media.info(pk) - but we don't have pk! // Option 3: Use media.getByUrl(url) - might exist in some versions // Option 4: Return the shortcode and hope feed functions accept it (sometimes works) // Option 5: Oembed (public, might give ID) let mediaId: string | null = null; try { // Try using getByUrl if it exists in the installed library version // @ts-ignore // Ignore potential TS error if method doesn't exist on type const mediaInfo = await this.ig.media.getByUrl(url); if (mediaInfo && mediaInfo.pk) { console.log(`[Helper] Found media PK ${mediaInfo.pk} using getByUrl for ${url}`); mediaId = mediaInfo.pk; // pk is the numeric ID } else { console.warn(`[Helper Warn] ig.media.getByUrl did not return expected info for ${url}.`); } } catch(lookupError: any) { console.warn(`[Helper Warn] Failed to get media PK using getByUrl for ${url}: ${lookupError.message}.`); // If getByUrl fails or doesn't exist, fall back to using the shortcode directly. // Note: Some feeds (like mediaComments) require the numeric PK and will fail with the shortcode. mediaId = shortcode; console.log(`[Helper] Falling back to using shortcode ${shortcode} as media ID for ${url}`); } if (!mediaId) { console.error(`[Helper Error] Could not resolve media ID for shortcode: ${shortcode}`); return null; } return mediaId; } catch (error: any) { console.error(`[Helper Error] Failed to get media ID from URL ${url}:`, error.message); if (error.name === 'IgNotFoundError') { return null; } return null; } }