Insta MCP Server

Instructions

Implementation Reference

• src/tools/search_accounts.ts:34-112 (handler)

  The 'execute' method contains the core handler logic for the 'instagram_search_accounts' tool. It validates input, checks login status, performs the user search via igpapiClient, limits and formats the results, and returns a structured ToolResult.

  async execute(args: { query: string; limit?: number }): Promise<ToolResult> {
    const { query, limit = 20 } = args;
  
    // Validate inputs
    if (!query || query.trim().length === 0) {
      throw new Error("Search query is required and cannot be empty");
    }
  
    const searchLimit = Math.min(Math.max(1, limit || 20), 50);
  
    // Check if logged in
    if (!igpapiClient.isLoggedIn()) {
      throw new Error("Not logged in. Please use the instagram_login tool to authenticate first.");
    }
  
    // Ensure client is initialized
    if (!igpapiClient.isInitialized()) {
      await igpapiClient.initialize();
    }
  
    const client = igpapiClient.getClient();
  
    try {
      // Perform account search
      const searchResponse = await client.user.search(query) as UserRepositorySearchResponseRootObject;
  
      // Extract users array from response
      // The response structure contains a 'users' property with the array of results
      const users = searchResponse.users || [];
      const totalResults = users.length;
  
      // Limit results
      const limitedResults = users.slice(0, searchLimit);
  
      // Format results
      if (limitedResults.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `No accounts found matching "${query}"`,
            },
          ],
        };
      }
  
      const formattedResults = limitedResults.map((user, index: number) => {
        const profile = {
          rank: index + 1,
          username: user.username || "N/A",
          fullName: user.full_name || "N/A",
          userId: user.pk || "N/A",
          isVerified: user.is_verified || false,
          isPrivate: user.is_private || false,
          followerCount: user.follower_count || 0,
        };
  
        return `\n${profile.rank}. @${profile.username}${profile.isVerified ? " ✓" : ""}
   Full Name: ${profile.fullName}
   User ID: ${profile.userId}
   ${profile.isPrivate ? "🔒 Private Account" : "🌐 Public Account"}
   Followers: ${profile.followerCount.toLocaleString()}`;
      }).join("\n");
  
      const summary = `Found ${limitedResults.length} account${limitedResults.length === 1 ? "" : "s"} matching "${query}"${totalResults > searchLimit ? ` (showing first ${searchLimit} of ${totalResults} total)` : ""}:`;
  
      return {
        content: [
          {
            type: "text",
            text: `${summary}${formattedResults}`,
          },
        ],
      };
    } catch (error) {
      // Re-throw to be handled by base error handling
      throw error;
    }
  }

• src/tools/search_accounts.ts:12-31 (schema)

  The 'getDefinition' method provides the tool schema, including name 'instagram_search_accounts', description, and input schema requiring a 'query' string with optional 'limit'.

  getDefinition(): ToolDefinition {
    return {
      name: "instagram_search_accounts",
      description: "Search for Instagram accounts by username query. Returns a list of matching accounts with their profile information.",
      inputSchema: {
        type: "object",
        properties: {
          query: {
            type: "string",
            description: "The search query (username or name to search for)",
          },
          limit: {
            type: "number",
            description: "Maximum number of results to return (default: 20, max: 50)",
            default: 20,
          },
        },
        required: ["query"],
      },
    };

• src/tools/index.ts:9-28 (registration)

  The tool is imported and instantiated as 'new SearchAccountsTool()' in the central tools registry array, which is used by getAllToolDefinitions() for MCP registration and executeTool() for invocation.

  import { SearchAccountsTool } from "./search_accounts.js";
  import { LogoutTool } from "./logout.js";
  import { GetUserProfileTool } from "./get_user_profile.js";
  import { GetCurrentUserProfileTool } from "./get_current_user_profile.js";
  import { GetUserPostsTool } from "./get_user_posts.js";
  import { LikePostTool } from "./like_post.js";
  import { LikeCommentTool } from "./like_comment.js";
  import { CommentOnPostTool } from "./comment_on_post.js";
  import { GetPostCommentsTool } from "./get_post_comments.js";
  import { GetPostDetailsTool } from "./get_post_details.js";
  import { GetUserStoriesTool } from "./get_user_stories.js";
  import { GetTimelineFeedTool } from "./get_timeline_feed.js";
  import { FollowUserTool } from "./follow_user.js";
  import type { BaseTool } from "./base.js";
  
  // Import all tools
  const tools: BaseTool[] = [
    new LoginTool(),
    new Complete2FATool(),
    new SearchAccountsTool(),