Skip to main content
Glama

toolkit-mcp-server

by io.github.cyanheads

toolkit-mcp-server: geolocate IP

toolkit_geolocate_ip
Read-onlyIdempotent

Resolve a public IP address (or hostname) to geographic and network metadata: country, region, city, latitude/longitude, the owning ASN and organization, timezone, and the proxy/hosting/mobile quality flags. target accepts an IPv4/IPv6 address or a hostname — a hostname is DNS-resolved first and the resolvedIp field echoes which IP was actually located. The provider is called directly (never the target), so this is SSRF-free and safe to expose anywhere. Results are best-effort and provider-bounded: VPNs, proxies, mobile NAT, and anycast all defeat IP-to-location, accuracy is city-level at best, and many fields can be absent for reserved or thinly-documented ranges — absent fields are reported as unknown, never invented. Read proxy, hosting, and mobile before trusting the coordinates: a true on any of them means the location describes infrastructure, not the user. Private/reserved addresses have no public geolocation and are rejected. The source field names which provider answered.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
targetYesA public IPv4/IPv6 address or a hostname (e.g. "8.8.8.8" or "example.com").

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
asnNoAutonomous System number, e.g. "AS15169". Absent on providers that omit it.
orgNoOwning organization or ISP, e.g. "Google LLC". Absent when unknown.
cityNoCity name. Absent when unknown.
errorNoPresent when the call failed. Absent on success.
proxyNoTrue when the address is a known proxy, VPN, or Tor exit — the location describes the exit node, not the user. Absent when the provider does not report it.
mobileNoTrue when the address belongs to a mobile carrier network, where NAT can place the location far from the device. Absent when unreported.
regionNoRegion or state name. Absent when unknown.
sourceNoThe provider that answered the lookup, e.g. "ip-api".
targetNoThe target as supplied (IP or hostname).
countryNoCountry name. Absent when the provider does not report it.
hostingNoTrue when the address belongs to a hosting or datacenter network, so the location is a facility rather than a person. Absent when unreported.
latitudeNoLatitude in decimal degrees. Absent when unknown.
timezoneNoIANA timezone, e.g. "America/Los_Angeles". Absent when unknown.
longitudeNoLongitude in decimal degrees. Absent when unknown.
resolvedIpNoThe IP that was actually located (a supplied hostname is resolved to this first).
countryCodeNoISO 3166-1 alpha-2 country code. Absent when unknown.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds substantial behavioral context beyond annotations: it explains the SSRF-free nature, best-effort results with provider-bounded accuracy, how absent fields are reported (unknown, never invented), the meaning of proxy/hosting/mobile flags, and that private/reserved addresses are rejected. It also clarifies hostname resolution behavior and the resolvedIp echo.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-structured, front-loading the core purpose and then adding critical caveats. Every sentence adds value: the first sentence states the purpose, the second explains hostname handling, the third addresses safety, the fourth covers accuracy limitations, the fifth warns about proxy flags, and the sixth covers rejection of private addresses. No fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple input formats, provider-dependent behavior, quality flags, error conditions), the description is remarkably complete. It covers input handling, output semantics (resolvedIp, source field), limitations, safety, and error cases. The output schema exists, so return values are documented elsewhere, but the description still explains the meaning of key fields (proxy/hosting/mobile flags) which is essential for correct interpretation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the target parameter well. The description adds value by explaining that hostnames are DNS-resolved first and that the resolvedIp field echoes the actual IP located, which is not in the schema. It also clarifies the accepted formats (IPv4/IPv6/hostname) beyond the schema's patterns.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool resolves a public IP or hostname to geographic and network metadata, listing specific fields (country, region, city, lat/long, ASN, organization, timezone, quality flags). It distinguishes itself from siblings (encode, generate_id, generate_qr, hash_value) by its unique purpose of IP geolocation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool (resolving IPs/hostnames to location) and provides clear exclusions: private/reserved addresses are rejected, and it warns about VPNs/proxies/mobile NAT defeating accuracy. It also implicitly distinguishes from siblings by its specific domain, and notes the provider is called directly (SSRF-free) making it safe to expose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All toolkit-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.5/5.0
Disambiguation5/5

Each tool targets a distinct function: encoding, ID generation, QR generation, IP geolocation, and hashing. No two tools could plausibly be selected for the same task, and the descriptions reinforce these boundaries.

Naming Consistency5/5

All tools follow the exact toolkit_<verb>_<noun> snake_case pattern with action verbs (encode, generate, geolocate, hash). There are no mixed conventions or vague names.

Tool Count5/5

Five tools is within the ideal 3-15 range and each tool carries substantial functionality through multiple formats, algorithms, or operations. No tool feels like filler, and the set avoids bloat.

Completeness4/5

Each individual tool is internally comprehensive—encode covers four encodings in both directions, generate_id covers common ID formats, and hash covers generate/compare. As a general 'toolkit' it omits some common utility categories, but there are no dead ends or missing operations within the five advertised functions.

Resources