Skip to main content
Glama
IPInfo MCP Server

IPInfo MCP Server

MCP Server IPInfo

GitHub License GitHub Actions Workflow Status

This is a version of the MCP Server for IPInfo that implements the complete IPInfo OpenAPI specification with strongly-typed models and comprehensive tool coverage.

Features

  • Full OpenAPI Spec Implementation: Complete implementation of IPInfo's OpenAPI specification

  • Strongly Typed: All API responses use Pydantic models for type safety

  • HTTP Transport: Supports streamable-http transport with health endpoint

  • Comprehensive Tools: 25+ MCP tools covering all IPInfo API endpoints

  • Built-in Skill Resource: Serves a skill://ipinfo/usage resource that teaches LLMs optimal tool selection and context reuse patterns

Related MCP server: IP Lookup MCP

Installation

# Using uv (recommended)
uv pip install -e .

# Or with pip
pip install -e .

Configuration

Set your IPInfo API token as an environment variable:

export IPINFO_API_TOKEN=your_token_here

Running the Server

As a standalone MCP server

# Using uv
uv run mcp-ipinfo

# Or with Python
python -m mcp_ipinfo.server

In Claude Code

Add this configuration to your Claude Code settings:

{
  "mcpServers": {
    "ipinfo": {
      "command": "/path/to/.local/bin/uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-ipinfo",
        "run",
        "mcp-ipinfo"
      ],
      "env": {
        "IPINFO_API_TOKEN": "your_ipinfo_api_token_here"
      }
    }
  }
}

Skill Resource

The server includes a built-in skill at skill://ipinfo/usage that guides LLMs on:

  • Tool selection: Which tool to use for each intent (general lookup vs. VPN detection vs. WHOIS)

  • Context reuse: Carrying IP addresses across follow-up questions

  • VPN detection: Using the Plus API (get_plus_ip_info) instead of the Core API for privacy flags

The server's instructions field tells compatible MCP clients to read this resource before using tools. This is also published as a standalone skill at mpak.dev/skills/@nimblebraininc/ipinfo.

Available MCP Tools

Core IP Information

  • get_ip_info(ip?) - Get comprehensive IP information

  • get_plus_ip_info(ip) - Get full IP intelligence via Plus API (includes privacy detection)

  • get_account_info() - Get API account limits and features

  • batch_lookup(ips[]) - Batch lookup multiple IPs

  • summarize_ips(ips[]) - Get summary statistics for IP list

  • map_ips(ips[]) - Create visual map of IP locations

Company & Carrier

  • get_company_info(ip) - Get company details for an IP

  • get_carrier_info(ip) - Get mobile carrier information

Privacy & Security

  • get_plus_ip_info(ip) - Detect VPN, proxy, Tor, relay (via Plus API)

  • get_residential_proxy_info(ip) - Detect residential proxy services

  • get_abuse_contact(ip) - Get abuse contact information

Network Information

  • get_hosted_domains(ip, page?, limit?) - Get domains on an IP

  • get_ip_ranges(domain) - Get IP ranges for a domain

WHOIS Lookups

  • whois_lookup_by_ip(ip, page?, source?) - WHOIS by IP

  • whois_lookup_by_domain(domain, page?, source?) - WHOIS by domain

  • whois_lookup_by_asn(asn, page?, source?) - WHOIS by ASN

Single Field Tools

  • get_ip_city(ip?) - Get just the city

  • get_ip_country(ip?) - Get just the country code

  • get_ip_region(ip?) - Get just the region/state

  • get_ip_location(ip?) - Get just the coordinates

  • get_ip_postal(ip?) - Get just the postal code

  • get_ip_timezone(ip?) - Get just the timezone

  • get_ip_hostname(ip?) - Get just the hostname

  • get_ip_org(ip?) - Get just the organization/ASN

Testing

Run the test client to verify the implementation:

python test_client.py

API Client Usage

You can also use the API client directly in your Python code:

import asyncio
from mcp_ipinfo.api_client import IPInfoClient

async def main():
    async with IPInfoClient() as client:
        # Get current IP info
        info = await client.get_current_info()
        print(f"Current IP: {info.ip}")
        print(f"Location: {info.city}, {info.country}")

        # Get specific IP info
        google = await client.get_info_by_ip("8.8.8.8")
        print(f"Google DNS: {google.org}")

        # Privacy detection via Plus API
        plus_info = await client.get_plus_info("1.1.1.1")
        print(f"VPN detected: {plus_info.anonymous.is_vpn}")
        print(f"ASN: {plus_info.as_info.asn}")

asyncio.run(main())

Type Safety

All models are strongly typed using Pydantic:

from mcp_ipinfo.api_models import (
    FullResponse,      # Basic IP information
    PlusResponse,      # Comprehensive IP intelligence (geo, ASN, privacy)
    CompanyResponse,   # Company information
    RangesResponse,    # IP ranges for a domain
    # ... and many more
)

Requirements

  • Python 3.13+

  • aiohttp

  • fastmcp

  • pydantic

  • mcp

About

Part of the NimbleTools ecosystem. From the makers of NimbleBrain.

License

MIT

Available Tools

23 tools
batch_lookupB

Batch lookup multiple IP addresses.

Args: ips: List of IP addresses to lookup (can include field paths like "8.8.8.8/city")

Returns: Dictionary with IP information for each address.

Inputs: ips (required). Returns: object

get_abuse_contactB

Get abuse contact information for an IP address.

Args: ip: IP address to lookup

Returns: Abuse contact details including email, phone, and address.

Inputs: ip (required). Returns: name, email, phone, address, +2 more

get_account_infoB

Get IPInfo account information and API limits.

Returns: Account information including API limits and available features.

Inputs: no named parameters. Returns: token, features, requests

get_asn_infoC

Get information about an Autonomous System Number (ASN).

Args: asn: The ASN number (without 'AS' prefix)

Returns: ASN information including prefixes, peers, and network details.

Inputs: asn (required). Returns: asn, name, type, peers, +10 more

get_carrier_infoA

Get mobile carrier information for an IP address.

Args: ip: IP address to lookup

Returns: Mobile carrier details including MCC and MNC codes.

Inputs: ip (required). Returns: mcc, mnc, name

get_company_infoC

Get company information for an IP address.

Args: ip: IP address to lookup

Returns: Company name, domain, and type.

Inputs: ip (required). Returns: name, type, domain

get_hosted_domainsC

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.

Inputs: ip (required), limit, page. Returns: ip, page, total, domains

get_ip_cityA

Get just the city for an IP address.

Args: ip: IP address to lookup. If None, returns current city.

Returns: City name.

Inputs: ip. Returns: result

get_ip_countryA

Get just the country code for an IP address.

Args: ip: IP address to lookup. If None, returns current country.

Returns: Two-letter country code (ISO-3166).

Inputs: ip. Returns: result

get_ip_hostnameA

Get just the hostname for an IP address.

Args: ip: IP address to lookup. If None, returns current hostname.

Returns: Hostname.

Inputs: ip. Returns: result

get_ip_infoA

Get comprehensive information about an IP address.

Args: ip: IP address to lookup. If None, returns info about current IP. ctx: MCP context

Returns: Complete IP information including location, ASN, company, privacy, etc.

Inputs: ip (required). Returns: ip, asn, loc, org, +12 more

get_ip_locationA

Get just the coordinates for an IP address.

Args: ip: IP address to lookup. If None, returns current location.

Returns: Latitude,longitude coordinates.

Inputs: ip. Returns: result

get_ip_orgA

Get just the organization/ASN for an IP address.

Args: ip: IP address to lookup. If None, returns current organization.

Returns: ASN and organization name.

Inputs: ip. Returns: result

get_ip_postalA

Get just the postal code for an IP address.

Args: ip: IP address to lookup. If None, returns current postal code.

Returns: Postal or ZIP code.

Inputs: ip. Returns: result

get_ip_rangesB

Get IP ranges owned by a domain/organization.

Args: domain: Domain name to lookup

Returns: IP ranges information including IPv4 and IPv6 blocks.

Inputs: domain (required). Returns: domain, ranges, num_ranges, redirects_to

get_ip_regionA

Get just the region/state for an IP address.

Args: ip: IP address to lookup. If None, returns current region.

Returns: Region or state name.

Inputs: ip. Returns: result

get_ip_timezoneA

Get just the timezone for an IP address.

Args: ip: IP address to lookup. If None, returns current timezone.

Returns: IANA timezone string.

Inputs: ip. Returns: result

get_privacy_infoA

Detect privacy services (VPN, proxy, Tor, etc.) for an IP address.

Args: ip: IP address to check

Returns: Privacy detection results including VPN, proxy, Tor, relay, and hosting status.

Inputs: ip (required). Returns: tor, vpn, proxy, relay, +2 more

map_ipsB

Create a visual map of IP address locations.

Args: ips: List of IP addresses to map (up to 500,000)

Returns: Map report with visualization URL.

Inputs: ips (required). Returns: object

summarize_ipsC

Summarize a list of IP addresses with statistics and insights.

Args: ips: List of IP addresses to summarize (up to 500,000)

Returns: Summary report with statistics and map URL.

Inputs: ips (required). Returns: object

whois_lookup_by_asnB

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.

Inputs: asn (required), page, source. Returns: object

whois_lookup_by_domainC

WHOIS lookup by organization domain.

Args: domain: Domain name to lookup page: Page number for paginated results source: Filter by WHOIS source (arin, ripe, afrinic, apnic, lacnic)

Returns: WHOIS records for the domain.

Inputs: domain (required), page, source. Returns: object

whois_lookup_by_ipB

WHOIS lookup by IP address or IP range.

Args: ip: IP address or range to lookup page: Page number for paginated results source: Filter by WHOIS source (arin, ripe, afrinic, apnic, lacnic)

Returns: WHOIS records for the IP or range.

Inputs: ip (required), page, source. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 23 tools

    Disambiguation3/5

    Most tools have distinct purposes, but there is significant overlap between the single-field IP lookup tools (e.g., get_ip_city, get_ip_country, get_ip_hostname) and the comprehensive get_ip_info, which could cause confusion about which to use. The WHOIS tools are well-differentiated by target (ASN, domain, IP).

    Naming Consistency4/5

    The naming follows a consistent verb_noun pattern (e.g., get_ip_info, get_asn_info, whois_lookup_by_domain) with minor deviations like batch_lookup (missing 'get_' prefix) and map_ips/summarize_ips (using verbs instead of 'get_'). Overall, it's readable and predictable.

    Tool Count2/5

    With 23 tools, the count feels excessive for an IP information server. Many tools are redundant (e.g., multiple single-field IP lookups) or could be consolidated (e.g., WHOIS lookups into one tool with parameters). This may overwhelm agents and increase misselection risk.

    Completeness5/5

    The toolset comprehensively covers the IP information domain, including IP lookups (batch, single, detailed, specific fields), ASN/company/carrier info, abuse contacts, privacy detection, WHOIS lookups, mapping, summarization, and account management. No obvious gaps exist for core workflows.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables IP address intelligence lookup including geolocation, network information, privacy detection (VPN/proxy/Tor), company data, and abuse contacts using IPLocate.io API. Supports both IPv4 and IPv6 addresses with comprehensive analysis tools and security assessment capabilities.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides IP address geolocation and lookup via ip-api.com, no authentication required for basic usage.
      85 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides IP geolocation data via ipinfo.io, enabling querying IP addresses for location, ISP, and other details through natural language.
      280 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables IP address lookups and risk assessments for IPv4/IPv6, providing geolocation, ISP/ASN, and security flags such as VPN, proxy, Tor, datacenter, and mobile with a risk score.
      87 npm
      MIT