RoxyAPI Astrology MCP server

Official

by RoxyAPI

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

Planetary Return Chart - Saturn return, Jupiter return, and inner planet cycles

post_astrology_planetary_returns

Read-only

Calculate Mercury, Venus, Mars, Jupiter, or Saturn return charts from birth data to find when a planet conjuncts its natal degree and begins a new cycle.

Instructions

Generate a planetary return chart for Mercury, Venus, Mars, Jupiter, or Saturn. A planetary return occurs when a transiting planet conjuncts its natal longitude, marking the beginning of a new cycle. Saturn return (~29 years) is the most significant life milestone in Western astrology. Jupiter return (~12 years) signals expansion and growth phases. Mars return (~2 years) resets energy and drive. Returns full tropical zodiac chart with all planetary positions, house cusps, and aspects. Planetary return chart API, Saturn return calculator, Jupiter return chart, Mars return forecast.

Input Schema

Name	Required	Description	Default
`lang`	No	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.	en
`planet`	Yes	Planet for the return calculation. Supports Mercury (~88 days), Venus (~225 days), Mars (~687 days), Jupiter (~12 years), and Saturn (~29 years). Saturn return is a major life milestone in Western astrology.
`compact`	No	Set true for the same data in a compact shape: arrays of same-shaped objects arrive columnar as {"__cols":[names],"__rows":[[values]]}. Lossless, typically 40 to 52 percent fewer tokens.
`latitude`	Yes	Latitude of the return location in decimal degrees (-90 to 90). Affects house cusps and Ascendant of the return chart.
`timezone`	Yes	Decimal hours from UTC OR IANA name (e.g. "America/New_York"). IANA resolved to the DST-correct offset for the birthDate. Output datetime is adjusted to this timezone.
`birthDate`	Yes	Original birth date in YYYY-MM-DD format. Used to determine the natal longitude of the selected planet.
`birthTime`	Yes	Original birth time in 24-hour HH:MM:SS format. Determines exact natal planet position for return timing.
`longitude`	Yes	Longitude of the return location in decimal degrees (-180 to 180).
`houseSystem`	No	House system for the return chart. Placidus (default), Whole Sign, Equal, or Koch.	placidus
`approximateDate`	Yes	Approximate date near the expected planetary return (YYYY-MM-DD). The return nearest this date is returned, so a date off by months still lands on a genuine return; during a retrograde loop the planet crosses its natal degree up to three times and the crossing nearest the date is the one returned.

Output Schema

Name	Required	Description	Default
`chart`	Yes
`planet`	Yes
`location`	Yes
`birthDate`	Yes
`returnDate`	Yes
`interpretation`	Yes
`approximateCycle`	Yes
`natalPlanetPosition`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.1.2Oct 5, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "approximateDate": "2026-08-15",
-    "birthDate": "1990-07-15",
-    "birthTime": "14:30:00",
-    "latitude": 40.7128,
-    "longitude": -74.006,
-    "planet": "Jupiter",
-    "timezone": -5
-  }
-]New value: +[
+  {
+    "approximateDate": "2026-08-15",
+    "birthDate": "1990-07-15",
+    "birthTime": "14:30:00",
+    "latitude": 40.7128,
+    "longitude": -74.006,
+    "planet": "Jupiter",
+    "timezone": "America/New_York"
+  }
+]

changedInput schema / properties / timezone / example

Previous value: --5New value: +"America/New_York"

First observedv0.1.0Oct 4, 2026

TDQS

A3.6/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds what the chart contains (planetary positions, house cusps, aspects), but says nothing about authentication, rate limits, or how a retrograde multi-crossing return is disambiguated at the description level.

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

Conciseness3/5

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

The opening two sentences are well front-loaded and informative, but the trailing 'Planetary return chart API, Saturn return calculator, Jupiter return chart, Mars return forecast' is keyword-stuffed filler that repeats the title, and the Saturn-return milestone claim duplicates the schema text.

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

Completeness4/5

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

With an output schema present, return values need no explanation, and the description adequately conveys purpose and planetary scope for a 10-parameter, 7-required tool. Only the absence of explicit sibling routing keeps it from being fully complete.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter, including the retrograde/approximateDate nuance, is already documented in the schema. The description only restates the planet options and cycle lengths, adding no syntax or format detail beyond structured fields, so the baseline 3 applies.

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?

States a specific verb (Generate) plus the resource (planetary return chart) and enumerates the exact supported planets, which cleanly separates it from post_astrology_solar_return and post_astrology_lunar_return without opening either schema.

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

Usage Guidelines3/5

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

The description explains what a planetary return is and how long each cycle lasts, which implies when the tool is relevant, but it never states when to prefer it over the solar/lunar return siblings or any prerequisites. Usage is inferable rather than explicit.

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

Deploy Server