IPInfo MCP Server

Instructions

Implementation Reference

• src/mcp_ipinfo/server.py:345-366 (handler)

  The main handler function for the 'whois_lookup_by_asn' MCP tool, decorated with @mcp.tool() for automatic registration. It retrieves the IPInfo client, converts the source parameter, calls the client's get_whois_net_by_asn method, and returns the result as a dictionary.

  @mcp.tool()
  async def whois_lookup_by_asn(
      asn: int, ctx: Context[Any, Any, Any], page: int | None = None, source: str | None = None
  ) -> dict[str, Any]:
      """WHOIS lookup by ASN.
  
      Args:
          asn: ASN number to lookup
          page: Page number for paginated results
          source: Filter by WHOIS source (arin, ripe, afrinic, apnic, lacnic)
  
      Returns:
          WHOIS records for the ASN.
      """
      client = get_client(ctx)
      whois_source = WhoisSource(source) if source else None
      try:
          result = await client.get_whois_net_by_asn(asn, page, whois_source)
          return result.model_dump(exclude_none=True)
      except IPInfoAPIError as e:
          ctx.error(f"API error: {e.message}")
          raise

• src/mcp_ipinfo/api_client.py:277-288 (helper)

  Helper method in IPInfoClient that makes the HTTP GET request to the IPInfo API's /whois/net/AS{asn} endpoint with optional page and source parameters, and parses the response into WhoisAsnResponse model.

  async def get_whois_net_by_asn(
      self, asn: int, page: int | None = None, source: WhoisSource | None = None
  ) -> WhoisAsnResponse:
      """Get WHOIS information by ASN."""
      params: dict[str, Any] = {}
      if page is not None:
          params["page"] = page
      if source:
          params["source"] = source.value
  
      data = await self._request("GET", f"/whois/net/AS{asn}", params=params or None)
      return WhoisAsnResponse(**data)

• src/mcp_ipinfo/api_models.py:147-152 (schema)

  Pydantic BaseModel defining the structure of the WHOIS response for ASN lookups, used by the client to validate and serialize API responses.

  class WhoisAsnResponse(BaseModel):
      net: str | None = None
      total: int | None = None
      page: int | None = None
      records: list[WhoisRecord] | None = None

• src/mcp_ipinfo/api_models.py:15-20 (schema)

  Enum defining valid WHOIS sources used as input parameter for filtering results.

  class WhoisSource(str, Enum):
      ARIN = "arin"
      RIPE = "ripe"
      AFRINIC = "afrinic"
      APNIC = "apnic"
      LACNIC = "lacnic"

• src/mcp_ipinfo/server.py:29-38 (helper)

  Utility function to obtain or lazily initialize the singleton IPInfoClient instance, checking for API token from environment.

  def get_client(ctx: Context[Any, Any, Any]) -> IPInfoClient:
      """Get or create the API client instance."""
      global _client
      if _client is None:
          api_token = os.environ.get("IPINFO_API_TOKEN")
          if not api_token:
              ctx.warning("IPINFO_API_TOKEN is not set - some features may be limited")
          _client = IPInfoClient(api_token=api_token)
      return _client