IP Geolocation MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/mcp_server_ipinfo/server.py:45-174 (handler)

  The core handler function for the 'get_ip_details' tool. Decorated with @mcp.tool() for registration. Validates input IP, checks cache, performs lookup via ipinfo_lookup, handles errors, and returns IPDetails object.
  @mcp.tool() async def get_ip_details( ip: Annotated[ str | None, Field( description="The IP address to analyze (IPv4 or IPv6). If None or not provided, analyzes the requesting client's IP address.", examples=["8.8.8.8", "2001:4860:4860::8888", None], ), ] = None, ctx: Context = None, ) -> IPDetails: """Get detailed information about an IP address including location, ISP, and network details. This tool provides comprehensive IP address analysis including geographic location, internet service provider information, network details, and security context. Use when you need to understand the user's location, ISP, and network details or those of a given IP address. Common use cases: - Analyze user's current location and connection details (leave ip parameter blank) - Investigate suspicious IP addresses for security analysis - Determine geographic distribution of website visitors or API users - Look up ISP and hosting provider information for network troubleshooting - Get timezone information for scheduling or time-sensitive operations - Verify if an IP belongs to a VPN, proxy, or hosting provider - Check country-specific compliance requirements (EU, etc.) Args: ip: The IP address to analyze (IPv4 or IPv6). If None or not provided, analyzes the requesting client's IP address. ctx: The MCP request context. Returns: IPDetails: Comprehensive IP information including: Basic Info: - ip: The IP address that was analyzed - hostname: Associated hostname/domain name - org: Organization/ISP name (e.g., "Google LLC", "Comcast Cable") - ts_retrieved: The timestamp when the IP address was looked up (UTC) Geographic Location: - city: City name - region: State/province/region name - country: Two-letter ISO country code (e.g., "US", "GB") - country_name: Full country name - postal: ZIP/postal code - loc: Coordinates as "latitude,longitude" string - latitude/longitude: Separate coordinate values - timezone: IANA timezone identifier (e.g., "America/New_York") Regional Info: - continent: Continent information dictionary - country_flag: Country flag image data - country_flag_url: URL to country flag image - country_currency: Currency information for the country - isEU: True if country is in European Union Network/Security Info (some features require paid API plan): - asn: Autonomous System Number details - privacy: VPN/proxy/hosting detection data - carrier: Mobile network operator info (for cellular IPs) - company: Company/organization details - domains: Associated domain names - abuse: Abuse contact information - bogon: True if IP is in bogon/reserved range - anycast: True if IP uses anycast routing Examples: # Get your own IP details my_info = get_ip_details() # Analyze a specific IP server_info = get_ip_details("8.8.8.8") # Check if IP is from EU for GDPR compliance details = get_ip_details("192.168.1.1") is_eu_user = details.isEU Note: Some advanced features (ASN, privacy detection, carrier info) require an IPINFO_API_TOKEN environment variable with a paid API plan. Basic location and ISP info works without authentication. """ ctx.info(f"Getting details for IP address {ip}") if "IPINFO_API_TOKEN" not in os.environ: ctx.warning("IPINFO_API_TOKEN is not set") if ip in ("null", "", "undefined", "0.0.0.0", "::"): ip = None # If IP address given, check cache first if ip and (cached := cache.get(ip)): ctx.debug(f"Returning cached result for {ip}") return cached if ip: try: parsed_ip = ipaddress.ip_address(ip) if parsed_ip.is_private: raise ToolError( f"{ip} is a private IP address. Geolocation may not be meaningful." ) elif parsed_ip.is_loopback: raise ToolError( f"{ip} is a loopback IP address. Geolocation may not be meaningful." ) elif parsed_ip.is_multicast: raise ToolError( f"{ip} is a multicast IP address. Geolocation may not be meaningful." ) elif parsed_ip.is_reserved: raise ToolError( f"{ip} is a reserved IP address. Geolocation may not be meaningful." ) except ValueError: ctx.error(f"Got an invalid IP address: {ip}") raise ToolError(f"{ip} is not a valid IP address") try: result = ipinfo_lookup(ip) cache.set(result.ip, result) return result except Exception as e: ctx.error(f"Failed to look up IP details: {str(e)}") raise ToolError(f"Lookup failed for IP address {str(e)}")
• src/mcp_server_ipinfo/models.py:5-122 (schema)

  Pydantic model defining the output schema IPDetails with all fields for IP geolocation, ISP, ASN, privacy, etc.
  class IPDetails(BaseModel): """ A Pydantic model representing detailed information about an IP address. This model contains geographical, network, and additional metadata about an IP address, including location coordinates, country information, ISP details, and timezone data. """ ip: IPvAnyAddress = None # type: ignore """The IP address (supports both IPv4 and IPv6 formats)""" hostname: str | None = None """The hostname associated with the IP address, if available""" city: str | None = None """The city where the IP address is located""" region: str | None = None """The region/state where the IP address is located""" country: constr(pattern=r"^[A-Z]{2}$") | None = None """The two-letter ISO country code (e.g., 'US', 'GB', 'DE')""" loc: str | None = None """The geographical coordinates in the format 'latitude,longitude'""" org: str | None = None """The organization/ISP associated with the IP address (free plan only; paid plan: see `asn` field)""" postal: str | None = None """The postal/ZIP code of the IP address location""" timezone: str | None = None """The timezone of the IP address location (e.g., 'America/New_York')""" country_name: str | None = None """The full name of the country""" isEU: bool | None = None """Boolean indicating if the country is in the European Union""" country_flag_url: HttpUrl | None = None """URL to the country's flag image""" country_flag: dict | None = None """Dictionary containing country flag information""" country_currency: dict | None = None """Dictionary containing country currency information with fields: - code: str - The three-letter currency code (e.g., 'USD', 'EUR', 'GBP') - symbol: str - The currency symbol (e.g., '$', '€', '£')""" continent: dict | None = None """Dictionary containing continent information with fields: - code: str - The two-letter continent code (e.g., 'NA', 'EU', 'AS') - name: str - The full continent name (e.g., 'North America', 'Europe', 'Asia')""" latitude: condecimal(ge=-90, le=90) | None = None """The latitude coordinate, ranging from -90 to 90 degrees""" longitude: condecimal(ge=-180, le=180) | None = None """The longitude coordinate, ranging from -180 to 180 degrees""" asn: dict | None = None """Dictionary containing ASN information with fields (Basic, Standard, Business, and Enterprise plans only): - asn: str - The ASN number - name: str - The name of the ASN - domain: str - The domain of the ASN - route: str - The route of the ASN - type: str - The type of the ASN""" privacy: dict | None = None """Dictionary containing privacy information with fields (Standard, Business, and Enterprise plans only): - vpn: bool - Whether the IP address is in a VPN - proxy: bool - Whether the IP address is in a proxy - tor: bool - Whether the IP address is in a Tor exit node - relay: bool - Whether the IP address is in a relay node - hosting: bool - Whether the IP address is in a hosting provider - service: bool - Whether the IP address is in a service provider""" carrier: dict | None = None """Dictionary containing mobile operator information with fields (Business and Enterprise plans only): - name: str - The name of the mobile operator - mcc: str - The Mobile Country Code of the mobile operator - mnc: str - The Mobile Network Code of the mobile operator""" company: dict | None = None """Dictionary containing company information with fields (Business and Enterprise plans only): - name: str - The name of the company - domain: HttpUrl - The domain of the company - type: str - The type of the company""" domains: dict | None = None """Dictionary containing domains information with fields (Business and Enterprise plans only): - ip: IPvAnyAddress - The IP address of the domain - total: int - The total number of domains associated with the IP address - domains: list[HttpUrl] - The list of domains associated with the IP address""" abuse: dict | None = None """Dictionary containing abuse contact information with fields (Business and Enterprise plans only): - address: str - The address of the abuse contact - country: str - The country of the abuse contact - email: str - The email of the abuse contact - phone: str - The phone number of the abuse contact - network: str - The network of the abuse contact""" bogon: bool | None = None """Boolean indicating if the IP address is a bogon IP address. A bogon IP address is an IP address that is not assigned to a network and is used for testing or other purposes. This is not a reliable indicator of the IP address's location. """ anycast: bool | None = None """Boolean indicating if the IP address is an anycast IP address""" ts_retrieved: str | None = None """The timestamp of the IP address lookup"""
• src/mcp_server_ipinfo/ipinfo.py:9-49 (helper)

  Helper function that performs the actual IPInfo API lookup and maps response to IPDetails model.
  def ipinfo_lookup(ip: str | None, **kwargs) -> IPDetails: """ Retrieve detailed information about an IP address using the ipinfo.io service. This function fetches comprehensive information about the specified IP address, including geolocation data, ISP details, and country information. If no IP is provided, it returns information about the client's current IP address. Args: ip: The IP address to look up. If None, returns information about the client's current IP address. **kwargs: Additional arguments to pass to the ipinfo handler. These can include timeout settings, cache settings, or other ipinfo.io options. Returns: IPDetails: A Pydantic model containing detailed information about the IP, including location, organization, and country details. Raises: ipinfo.exceptions.RequestQuotaExceededError: If the API request quota is exceeded ipinfo.exceptions.RequestFailedError: If the API request fails ValueError: If the provided IP address is invalid Example: >>> details = ipinfo_lookup("8.8.8.8") >>> print(details.country) 'US' >>> print(details.org) 'Google LLC' """ handler = ipinfo.getHandler( access_token=os.environ.get("IPINFO_API_TOKEN", None), headers={"user-agent": "mcp-server-ipinfo", "custom_header": "yes"}, **kwargs, ) details = handler.getDetails(ip_address=ip) return IPDetails(**details.all, ts_retrieved=str(datetime.now(timezone.utc)))
• src/mcp_server_ipinfo/cache.py:6-24 (helper)

  In-memory cache class for IP lookup results with TTL to reduce API calls.
  class IPInfoCache: """ A cache for IPInfo API responses. """ def __init__(self, ttl_seconds: int = 3600): self.cache = {} self.ttl_seconds = ttl_seconds def get(self, ip: str) -> IPDetails | None: if ip in self.cache: data, timestamp = self.cache[ip] if datetime.now() - timestamp < timedelta(seconds=self.ttl_seconds): return data return None def set(self, ip: str, data: IPDetails): self.cache[ip] = (data, datetime.now())
• src/mcp_server_ipinfo/server.py:45-45 (registration)

  The @mcp.tool() decorator registers the get_ip_details function as an MCP tool.
  @mcp.tool()