IP Geolocation

by briandconnelly

16 stars

214 downloads

Not rated

GitHub

About

Integrates with ipinfo.io API to provide IP geolocation services, enabling location-based insights and network analysis.

Details

Author: briandconnelly
Repository: briandconnelly/mcp-server-ipinfo
GitHub stars: 16
Downloads: 214
License: MIT License
Categories: Design, Developer Tools, AI, Frontend, Security, Knowledge Base, Infrastructure, Other

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name IP Geolocation

Command (node, npx, python, etc.) uvx
Arguments
- Argument 1 mcp-server-ipinfo
Environment
- IPINFO_API_TOKEN <YOUR TOKEN>
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "ip geolocation": {
            "command": "uvx",
            "args": [
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "ip geolocation": {
            "command": "cmd",
            "args": [
                "/c",
                "uvx",
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "ip geolocation": {
            "command": "uvx",
            "args": [
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "ip geolocation": {
            "command": "uvx",
            "args": [
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "ip geolocation": {
            "command": "cmd",
            "args": [
                "/c",
                "uvx",
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "ip geolocation": {
            "command": "uvx",
            "args": [
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "ip geolocation": {
            "command": "uvx",
            "args": [
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "ip geolocation": {
            "command": "cmd",
            "args": [
                "/c",
                "uvx",
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "ip geolocation": {
            "command": "uvx",
            "args": [
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "ip geolocation": {
            "command": "uvx",
            "args": [
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "ip geolocation": {
            "command": "cmd",
            "args": [
                "/c",
                "uvx",
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "ip geolocation": {
            "command": "uvx",
            "args": [
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "ip geolocation": {
            "command": "uvx",
            "args": [
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "ip geolocation": {
            "command": "cmd",
            "args": [
                "/c",
                "uvx",
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "ip geolocation": {
            "command": "uvx",
            "args": [
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

From the repository

| Variable | Description | Default |
|----------|-------------|---------|
| IPINFO_API_TOKEN | IPInfo API token. Without it the server runs in free Lite mode. | unset (Lite) |
| IPINFO_CACHE_TTL | Per-IP cache TTL in seconds. Cached results retain their original ts_retrieved timestamp. | 3600 |
| IPINFO_CACHE_SIZE | Maximum cache entries before oldest-first eviction. | 4096 |

`ipinfo_lookup_my_ip`

Geolocate the calling client's own IP. Takes no arguments. On stdio transports the result reflects this server's outbound IP, not the end user's.

`ipinfo_lookup_ips`

Geolocate one or more specified IPs. Parameters: ips (list of strings), detail (optional string, defaults to 'summary').

`ipinfo_summarize_ips`

Geolocate and aggregate a batch into fixed-size counts and percentages by country, continent, ASN, and/or privacy flags. Parameters: ips (list of strings), group_by (optional tuple, defaults to ('country', 'asn')), top_n (optional integer, defaults to 50).

`ipinfo_check_residential_proxy`

Check whether an IP is a known residential-proxy exit node. Parameters: ip (string).

`ipinfo_generate_map_url`

Build an interactive ipinfo.io map for a set of IPs. Parameters: ips (list of strings). Returns a MapResult with the URL and details about the mapped IPs.

- ipinfo_lookup_my_ip() — Geolocate the calling client's own IP. Takes no arguments. On stdio transports the result reflects this server's outbound IP, not the end user's.
- ipinfo_lookup_ips(ips, detail="summary") — Geolocate one or more specified IPs. Defaults to detail="summary", which omits heavy nested blocks (continent, flags, currency, abuse, domains) for batch token savings; pass detail="full" for every field. Capped at 500,000 IPs per call. Invalid or special-use addresses (private, loopback, etc.) are filtered with ctx.warning() and excluded from the result list, as are IPs that fail upstream — match returned IPDetails.ip values back to your input to detect what was dropped. If every attempted lookup fails, a temporary api_error is raised.
- ipinfo_summarize_ips(ips, group_by=("country", "asn"), top_n=50) — Geolocate and aggregate a batch into fixed-size counts and percentages by country, continent, ASN, and/or privacy flags. Use this for large log-analysis tasks where per-IP records would waste context. Returns mapped, skipped, and failed counts plus capped top-N groups.
- ipinfo_check_residential_proxy(ip) — Check whether an IP is a known residential-proxy exit node. Tagged enterprise — requires the IPInfo residential-proxy add-on.
- ipinfo_generate_map_url(ips) — Build an interactive ipinfo.io map for a set of IPs. Returns a MapResult with the URL, the count that made the map, the IPs filtered out (with reasons, capped at 100), and a truncated flag.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "ip geolocation": {
            "command": "uvx",
            "args": [
                "mcp-server-ipinfo"
            ],
            "env": {
                "IPINFO_API_TOKEN": "<YOUR TOKEN>"
            }
        }
    }
}

Macos

{
    "command": "uvx",
    "args": [
        "mcp-server-ipinfo"
    ],
    "env": {
        "IPINFO_API_TOKEN": "<YOUR TOKEN>"
    }
}

Windows

{
    "command": "cmd",
    "args": [
        "/c",
        "uvx",
        "mcp-server-ipinfo"
    ],
    "env": {
        "IPINFO_API_TOKEN": "<YOUR TOKEN>"
    }
}

Linux

{
    "command": "uvx",
    "args": [
        "mcp-server-ipinfo"
    ],
    "env": {
        "IPINFO_API_TOKEN": "<YOUR TOKEN>"
    }
}

IP Geolocation MCP Server

A Model Context Protocol server that exposes the ipinfo.io API to AI agents. Geolocate IPv4 and IPv6 addresses, identify ISPs and ASNs, detect VPN/proxy/Tor exit nodes, and generate interactive maps for sets of IPs.

Installation

Sign up for a free IPInfo API token at <https://ipinfo.io/signup> if you don't have one. The server runs with no token (free Lite tier — country and ASN basics) but most fields require a token.

Claude Desktop (one-click bundle)

Download the .mcpb bundle from the latest release and open it to install in Claude Desktop. You can set your IPINFO_API_TOKEN (and optional cache tuning) in the install dialog; leave the token blank to run in the free Lite tier. The bundle launches the server with uv, so uv must be installed and on your system PATH (GUI apps don't inherit your shell's PATH).

Other MCP clients

Most MCP clients accept the following values:

| Field | Value |
|-------|-------|
| Command | uvx |
| Arguments | mcp-server-ipinfo |
| Environment | IPINFO_API_TOKEN = <YOUR TOKEN> |

Development Version

To run the latest from main:

| Field | Value |
|-------|-------|
| Command | uvx |
| Arguments | --from, git+https://github.com/briandconnelly/mcp-server-ipinfo, mcp-server-ipinfo |
| Environment | IPINFO_API_TOKEN = <YOUR TOKEN> |

Tools

Plan tiers

| Tier | Fields available |
|------|------------------|
| Free Lite (no token) | country, country_code, continent, ASN basics |
| Core | full geolocation, ASN details, privacy/VPN/proxy/Tor/hosting flags |
| Plus | adds carrier and company data |
| Enterprise | adds domains and abuse contacts |
| Residential-proxy add-on | enables ipinfo_check_residential_proxy. Sold separately on top of Enterprise; not included by default. |

Errors

Every tool raises a ToolError whose message is a JSON-encoded envelope with a stable code (invalid_ip_address, special_ip_unsupported, no_valid_ips, too_many_ips, auth_invalid, auth_insufficient_scope, quota_exceeded, timeout, api_error, unknown_error), a temporary flag, optional retry_after_ms, a repair hint, and a request_id correlation id. Agents should parse the message as JSON and branch on code. Each tool also advertises the subset of codes it can raise via meta.error_codes, so you can see the branch set from tool introspection.

Configuration

Environment Variables

License

MIT License — see LICENSE. Release history in CHANGELOG.md.

Disclaimer

This project is not affiliated with IPInfo.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

ipinfo_lookup_my_ip

ipinfo_lookup_ips

ipinfo_summarize_ips

ipinfo_check_residential_proxy

ipinfo_generate_map_url

Claude Desktop / Cursor

Macos

Windows

Linux

IP Geolocation MCP Server

Installation

Claude Desktop (one-click bundle)

Other MCP clients

Development Version

Tools

Plan tiers

Errors

Configuration

Environment Variables

License

Disclaimer

Install

More like this

Sentry

Github

Git

GitLab

Context 7

1Panel

`ipinfo_lookup_my_ip`

`ipinfo_lookup_ips`

`ipinfo_summarize_ips`

`ipinfo_check_residential_proxy`

`ipinfo_generate_map_url`