Chinese Astrology MCP Server by RoxyAPI

Convert lunar and Gregorian dates - Chinese lunisolar calendar API

post_chinese_astrology_calendar_lunar_date

Read-only

Convert a Gregorian date to the Chinese lunisolar calendar or convert a lunar date back, in one endpoint. The calendar is computed at the UTC+8 reference meridian with the month containing the winter solstice fixed as month 11 and the leap month placed as the first month of the cycle carrying no major solar term, so a lunar date is the same worldwide rather than shifting with the caller timezone. The response reports the length of the lunar month, whether the date sits in a leap month, and which month the year doubles if any. Built for festival calendars, birthday features that follow the lunar date, and any app that has to survive a leap month without shifting every date after it.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`date`	No	Gregorian date to convert to the lunisolar calendar. Send this OR the lunar fields, never both. Converts from the first day of lunar year 1551 to the last day of lunar year 2648, a little inside the supported date span, because numbering a lunar month needs the winter solstice on each side of it and placing a leap month needs the year before; a date outside that answers 400 date_out_of_range.
`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.
`lunarDay`	No	Day of the lunar month, 1 to 30. Requires lunarYear and lunarMonth.
`lunarYear`	No	Lunisolar year to convert back to a Gregorian date. Requires lunarMonth and lunarDay.
`lunarMonth`	No	Lunar month, 1 to 12. Requires lunarYear and lunarDay.
`isLeapMonth`	No	Set true to address the leap repetition of lunarMonth rather than the first pass. Requesting a leap month a year does not have returns 400.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`lunar`	Yes
`gregorianDate`	Yes
`leapMonthOfYear`	No
`referenceOffset`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 30, 2026

changedInput schema / properties / date / description

Previous value: -"Gregorian date to convert to the lunisolar calendar. Send this OR the lunar fields, never both."New value: +"Gregorian date to convert to the lunisolar calendar. Send this OR the lunar fields, never both. Converts from the first day of lunar year 1551 to the last day of lunar year 2648, a little inside the supported date span, because numbering a lunar month needs the winter solstice on each side of it and placing a leap month needs the year before; a date outside that answers 400 date_out_of_range."

Changed1 schema field changedSep 20, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "gregorianDate": {
+      "type": "string"
+    },
+    "leapMonthOfYear": {
+      "type": "number"
+    },
+    "lunar": {
+      "properties": {
+        "date": {
+          "type": "string"
+        },
+        "day": {
+          "type": "number"
+        },
+        "isLeapMonth": {
+          "type": "boolean"
+        },
+        "month": {
+          "type": "number"
+        },
+        "monthLength": {
+          "type": "number"
+        },
+        "year": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "year",
+        "month",
+        "day",
+        "isLeapMonth",
+        "monthLength",
+        "date"
+      ],
+      "type": "object"
+    },
+    "referenceOffset": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "gregorianDate",
+    "lunar",
+    "referenceOffset"
+  ],
+  "type": "object"
+}

First observedSep 1, 2026

TDQS

A4.1/5.0

Behavior5/5

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

With only readOnlyHint/destructiveHint annotations, the description carries real behavioral weight: it discloses the UTC+8 reference meridian, the month-11 winter-solstice fixing rule, the leap-month placement rule, and why a lunar date is timezone-invariant. It also flags range-limited error behavior via the schema, giving the agent operating semantics beyond the safety profile.

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 core conversion capability is front-loaded in the first clause, and the remaining sentences explain the calendrical rules that make the output trustworthy. The astronomical justification is slightly verbose but each sentence supports a decision the agent or its caller must make.

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?

For a 7-parameter, zero-required conversion endpoint with an output schema and read-only annotations, the description adequately covers the conversion model and the leap-month edge case. It could say more about which mode triggers on which input combination and how out-of-range lunars fail, but nothing essential is missing.

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% and all 7 parameters are documented there, including mutual exclusivity, ranges, and the leap-month flag, so the baseline is 3. The description adds conceptual meaning to the lunar fields (why a lunar date is globally stable) but no syntax or per-parameter detail beyond what the schema already supplies.

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 and resource ('Convert a Gregorian date to the Chinese lunisolar calendar or convert a lunar date back, in one endpoint'), covering both directions in a single scope. This bidirectional date-conversion scope is clearly separable from the day/month/solar-term siblings and from the bazi and zodiac tools.

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?

It names target use cases ('festival calendars, birthday features that follow the lunar date') but never states when to prefer this over a sibling such as the day or monthly endpoints, nor any exclusion. Usage is implied by the use-case list rather than explicitly routed.

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

All Chinese Astrology MCP Server by RoxyAPI tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?