RoxyAPI Astrology MCP server

Official

by RoxyAPI

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

Lunar Return Chart - Monthly emotional forecast with Moon cycle chart

post_astrology_lunar_return

Read-only

Generate a lunar return chart for monthly astrological forecasting. Get planetary positions, house cusps, aspects, and emotional themes for the coming month.

Instructions

Generate a lunar return chart for any month, cast for the exact moment the transiting Moon returns to its natal ecliptic longitude. The Moon completes one sidereal orbit every ~27.3 days, making this the primary technique for monthly astrological forecasting. Returns full tropical zodiac chart with planetary positions, house cusps, aspects, Ascendant, and Midheaven. Reveals emotional patterns, domestic focus, and intuitive themes for the coming month. Lunar return chart API, monthly horoscope forecast, Moon cycle chart, emotional astrology prediction.

Input Schema

TableJSON 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
`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 lunar return location in decimal degrees (-90 to 90). Affects the Ascendant and house cusps 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 natal Moon longitude for the lunar return calculation.
`birthTime`	Yes	Original birth time in 24-hour HH:MM:SS format. Determines exact natal Moon position for monthly return timing.
`longitude`	Yes	Longitude of the lunar return location in decimal degrees (-180 to 180). Determines local sidereal time for house calculations.
`returnDate`	Yes	Approximate date near the desired lunar return (YYYY-MM-DD). The Moon returns to its natal position every ~27.3 days, so provide a date within a few days of the expected return.
`houseSystem`	No	House system for the lunar return chart. Placidus (default), Whole Sign, Equal, or Koch.	placidus

Output Schema

TableJSON Schema

Name	Required	Description	Default
`chart`	Yes
`location`	Yes
`birthDate`	Yes
`interpretation`	Yes
`lunarReturnDate`	Yes
`natalMoonPosition`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 4, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful behavioral context by specifying the exact return condition and the chart contents: planetary positions, house cusps, aspects, Ascendant, and Midheaven. It also explains the interpretive scope ('emotional patterns, domestic focus, intuitive themes') without contradicting the annotations.

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 first three sentences are efficient and front-loaded with the core definition, cycle, and output contents. The final keyword sentence ('Lunar return chart API, monthly horoscope forecast, Moon cycle chart, emotional astrology prediction.') is redundant SEO-style phrasing that repeats the title and adds no operational value.

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?

Given 9 parameters, 100% schema coverage, an output schema, and read-only annotations, the description provides adequate context: it explains the astronomical trigger, the output chart contents, and the forecast use case. It does not need to describe return values because the output schema exists; the main missing piece, routing against sibling tools, is already accounted for under usage guidelines.

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 the baseline is 3 even though the description adds no parameter-level details. The prose reinforces the exact-moment calculation and the monthly return concept, but it does not add syntax, formats, or semantics beyond what the schema already provides.

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 opens with a specific verb+resource: 'Generate a lunar return chart for any month,' and precisely defines the trigger as the moment the transiting Moon returns to its natal ecliptic longitude. It clearly distinguishes this from sibling monthly transit/aspect tools by naming the exact astronomical technique and listing the returned chart components.

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

Usage Guidelines4/5

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

The description states that the lunar return is 'the primary technique for monthly astrological forecasting' and explains the ~27.3-day cycle, giving the agent a clear context for selecting this tool. It does not explicitly name sibling alternatives such as post_astrology_solar_return or post_astrology_planetary_returns, so it stops short of a full when-not-to-use statement.

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

Deploy Server