Skip to main content
Glama
IPGeolocation MCP Server

IPGeolocation MCP Server

Astronomy Data

get_astronomy
Read-only

Retrieve single-date sunrise, sunset, moonrise, moonset, twilight, day length, and sun/moon position for a latitude/longitude, location, or IP address.

Instructions

Read-only single-date astronomy lookup via GET /v3/astronomy. Works on free and paid plans. Cost: 1 credit. This endpoint covers one date or real-time sun/moon position; get_astronomy_time_series provides daily sunrise, moon, and twilight data across a date range.

Returns { location, astronomy } plus ip for IP/server-address lookups. astronomy includes date/current_time, sunrise/sunset, moonrise/moonset, twilight blocks, day_length, sun/moon position, distance, status, moon_phase, moon_illumination_percentage, and moon_angle.

Selector priority is lat/long, location, ip, then the server's public egress IP when no selector is provided. lat and long must be provided together; date must be YYYY-MM-DD; elevation is in meters, with a maximum of 10000; negative values are treated as 0. time_zone changes timestamp formatting to include full dates. lang only changes location fields; non-English lang is paid-only and returns 401 on free plans.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_astronomy"
  }
}

Input Schema

NameRequiredDescriptionDefault
ipNoIPv4 or IPv6 address to get astronomy data for that IP's location.
latNoLatitude coordinate. Highest priority. Must be used with long.
dateNoDate in YYYY-MM-DD format. Defaults to today.
langNoResponse language for location fields in IP-based lookups (en, de, ru, ja, fr, cn, es, cs, it, ko, fa, pt, ar). Paid plans only. Free plan returns 401 for non-English language values.
longNoLongitude coordinate. Must be used with lat.
locationNoCity or address string (e.g. San Francisco, CA).
elevationNoElevation in meters above sea level. Maximum 10000; negative values are treated as 0. Affects sunrise/sunset calculations for higher accuracy.
time_zoneNoIANA timezone name to express times in (e.g. America/New_York). If set, time fields include full date instead of just time.

Output Schema

NameRequiredDescriptionDefault
dataNoPresent on success: API result after field selection, redaction, and transport limits.
pageNo
errorNoPresent on failure, with isError: true.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.0.4
    • changedInput schema / properties / elevation / description
      Previous value: -"Elevation in meters above sea level (0-10000). Affects sunrise/sunset calculations for higher accuracy."New value: +"Elevation in meters above sea level. Maximum 10000; negative values are treated as 0. Affects sunrise/sunset calculations for higher accuracy."
  2. Changed2 schema fields changedv2.0.3
    • removedOutput schema / properties / data / additionalProperties / anyOf
      Removed value: -[
      -  {
      -    "type": "null"
      -  },
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "array"
      -  },
      -  {
      -    "type": "object"
      -  }
      -]
    • addedOutput schema / properties / data / additionalProperties / type
      Added value: +[
      +  "null",
      +  "boolean",
      +  "number",
      +  "string",
      +  "array",
      +  "object"
      +]
  3. Addedv2.0.1
  4. Removedv2.0.0
  5. First observedv1.0.10

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the readOnly and openWorld annotations, the description discloses plan availability, credit cost, selector fallback to the server's egress IP, paid-only language behavior with 401 on free plans, and parameter constraints such as elevation limits. These are meaningful operational details not available from annotations alone.

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

Conciseness4/5

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

The description is dense but front-loaded and structured around purpose, cost, return shape, selector behavior, and constraints. Some return-field detail is redundant because an output schema exists, but the text remains efficient overall.

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?

For an eight-parameter tool with an output schema, the description covers the important context: scope, sibling distinction, plan/cost behavior, selector priority, parameter constraints, and language limitations. An agent should be able to invoke it correctly without needing additional guidance.

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 already 100%, so the schema documents most parameter meanings. The description still adds useful cross-parameter semantics: selector priority is lat/long, then location, then ip, then server egress IP, and lat/long must be paired. Remaining parameter details largely repeat the schema.

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 states a specific read-only resource and operation: single-date astronomy lookup via GET /v3/astronomy. It explicitly distinguishes this from get_astronomy_time_series, which covers daily data across a date range.

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?

It gives clear when-to-use context: one date or real-time sun/moon position, versus the time-series sibling for daily sunrise, moon, and twilight data across a range. Selector priority and fallback behavior are also spelled out, leaving little ambiguity for an agent choosing inputs.

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