Instantly MCP Server

Instructions

Implementation Reference

• src/instantly_mcp/tools/leads.py:288-300 (handler)

  The handler function that executes the tool: fetches verification stats via API GET /lead-lists/{list_id}/verification-stats using the provided list_id from params, formats as JSON.

  async def get_verification_stats_for_lead_list(params: GetVerificationStatsInput) -> str:
      """
      Get email verification statistics for a lead list.
      
      Returns breakdown of verification results:
      - Valid emails
      - Invalid/bounced emails
      - Risky emails
      - Unknown status
      """
      client = get_client()
      result = await client.get(f"/lead-lists/{params.list_id}/verification-stats")
      return json.dumps(result, indent=2)

• src/instantly_mcp/models/leads.py:142-148 (schema)

  Pydantic input schema/model: requires list_id (str). Used for input validation in the handler.

  class GetVerificationStatsInput(BaseModel):
      """Input for getting email verification stats for a list."""
      
      model_config = ConfigDict(str_strip_whitespace=True, extra="ignore")
      
      list_id: str = Field(..., description="List UUID")

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

  Registration: The tool function is included in the LEAD_TOOLS list, which is collected and registered by server.py.

  LEAD_TOOLS = [
      list_leads,
      get_lead,
      create_lead,
      update_lead,
      list_lead_lists,
      create_lead_list,
      update_lead_list,
      get_verification_stats_for_lead_list,
      add_leads_to_campaign_or_list_bulk,
      delete_lead,
      delete_lead_list,
      move_leads_to_campaign_or_list,
  ]

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

  MCP annotation registration: Marks the tool as read-only in the TOOL_ANNOTATIONS dict used during tool registration.

  "get_verification_stats_for_lead_list": {"readOnlyHint": True},