IPInfo MCP Server

Instructions

Implementation Reference

• src/mcp_ipinfo/server.py:230-249 (handler)

  MCP tool handler for get_hosted_domains. Decorated with @mcp.tool() for registration and execution. Fetches domains via IPInfoClient.

  @mcp.tool()
  async def get_hosted_domains(
      ip: str, ctx: Context[Any, Any, Any], page: int | None = None, limit: int | None = None
  ) -> DomainsResponse:
      """Get domains hosted on an IP address.
  
      Args:
          ip: IP address to lookup
          page: Page number (starts at 0)
          limit: Number of results per page (max 1000, default 100)
  
      Returns:
          List of domains hosted on the IP address.
      """
      client = get_client(ctx)
      try:
          return await client.get_domains(ip, page, limit)
      except IPInfoAPIError as e:
          ctx.error(f"API error: {e.message}")
          raise

• src/mcp_ipinfo/api_models.py:61-65 (schema)

  Pydantic model defining the output schema for get_hosted_domains tool response.

  class DomainsResponse(BaseModel):
      ip: str | None = Field(None, description="IP address")
      page: int | None = Field(None, description="Page number")
      total: int = Field(..., description="Total domains")
      domains: list[str] | None = Field(None, description="List of domains")

• src/mcp_ipinfo/api_client.py:209-220 (helper)

  IPInfoClient method that performs the actual API request to ipinfo.io/domains/{ip} and parses response into DomainsResponse.

  async def get_domains(
      self, ip: str, page: int | None = None, limit: int | None = None
  ) -> DomainsResponse:
      """Get domains hosted on an IP."""
      params = {}
      if page is not None:
          params["page"] = page
      if limit is not None:
          params["limit"] = limit
  
      data = await self._request("GET", f"/domains/{ip}", params=params or None)
      return DomainsResponse(**data)