Instantly MCP Server

Instructions

Implementation Reference

• src/instantly_mcp/tools/leads.py:204-244 (handler)

  The main handler function implementing the list_lead_lists tool. Calls the Instantly API /lead-lists endpoint with pagination and filtering parameters, adds LLM-friendly pagination hints, and returns JSON.

  async def list_lead_lists(params: Optional[ListLeadListsInput] = None) -> str:
      """
      List lead lists with cursor-based pagination (100 per page).
      
      PAGINATION: If response contains pagination.next_starting_after, there are 
      MORE results. Call again with starting_after=<that value> to get next page.
      Continue until pagination.next_starting_after is null.
      
      Lead lists are containers for organizing leads outside of campaigns.
      Use has_enrichment_task filter to find lists with auto-enrichment enabled.
      """
      client = get_client()
      
      # Handle case where params is None (for OpenAI/non-Claude clients)
      # Set default limit=100 to return more results by default
      if params is None:
          params = ListLeadListsInput(limit=100)
      
      query_params = {}
      if params.limit:
          query_params["limit"] = params.limit
      else:
          # Default to 100 results if no limit specified
          query_params["limit"] = 100
      if params.starting_after:
          query_params["starting_after"] = params.starting_after
      if params.has_enrichment_task is not None:
          query_params["has_enrichment_task"] = params.has_enrichment_task
      if params.search:
          query_params["search"] = params.search
      
      result = await client.get("/lead-lists", params=query_params)
      
      # Add pagination guidance for LLMs
      if isinstance(result, dict):
          pagination = result.get("pagination", {})
          next_cursor = pagination.get("next_starting_after")
          if next_cursor:
              result["_pagination_hint"] = f"MORE RESULTS AVAILABLE. Call list_lead_lists with starting_after='{next_cursor}' to get next page."
      
      return json.dumps(result, indent=2)

• src/instantly_mcp/models/leads.py:102-115 (schema)

  Pydantic BaseModel defining the input parameters for the list_lead_lists tool, including pagination, search, and filter options.

  class ListLeadListsInput(BaseModel):
      """Input for listing lead lists with pagination."""
      
      # Use extra="ignore" to be tolerant of unexpected fields from LLMs
      model_config = ConfigDict(str_strip_whitespace=True, extra="ignore")
      
      limit: Optional[int] = Field(default=100, ge=1, le=100, description="Results per page (1-100, default: 100)")
      starting_after: Optional[str] = Field(
          default=None, 
          description="Pagination cursor - use value from pagination.next_starting_after to get next page"
      )
      has_enrichment_task: Optional[bool] = Field(default=None)
      search: Optional[str] = Field(default=None, description="Search by name")

• src/instantly_mcp/server.py:91-91 (registration)

  MCP tool registration annotation in server.py specifying that list_lead_lists is a read-only operation.

  "list_lead_lists": {"readOnlyHint": True},

• src/instantly_mcp/tools/leads.py:455-455 (registration)

  Inclusion of the list_lead_lists handler in the LEAD_TOOLS list for export and registration.

  list_lead_lists,

• src/instantly_mcp/models/__init__.py:30-30 (schema)

  Export of ListLeadListsInput schema model for use across the codebase.

  ListLeadListsInput,