chinese-astrology-skill
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@chinese-astrology-skillcalculate my BaZi chart for 2000-01-15 12:00, male"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Chinese Astrology Skill 🔮
The most comprehensive Chinese astrology AI skill — 4 tools covering BaZi (Four Pillars of Destiny), bone weight fortune telling, and Chinese almanac. Available as an Agent Skill (SKILL.md) and MCP server.
Built by Ba-Zi.ai — Free AI-powered BaZi calculator and Chinese astrology platform.
Features
Tool | Description | Unique? |
| Full BaZi (四柱八字) chart calculation with Ten Gods, Hidden Stems, Decade Fortune | — |
| Reverse-lookup: find birth dates from a BaZi string | — |
| Chinese almanac (黄历) with auspicious activities and directional gods | — |
| Yuan Tiangang bone weight fortune (秤骨算命) with 52 destiny poems | ✅ Exclusive |
What makes this different?
Bone Weight Fortune (秤骨算命) — The only MCP/Skill that includes Yuan Tiangang's 1,300-year-old bone weight calculation with all 52 classical poems and modern interpretations
Bilingual descriptions — All tool descriptions in both English and Chinese
Accurate calculations — Powered by tyme4ts, the most precise Chinese calendar library
Related MCP server: taibu
Quick Start
Claude Desktop / Claude Code
Add to your MCP config:
{
"mcpServers": {
"chinese-astrology": {
"command": "npx",
"args": ["-y", "chinese-astrology-skill"]
}
}
}Stdio Transport
npx chinese-astrology-skillHTTP Transport
git clone https://github.com/xlw-pro/chinese-astrology-skill.git
cd chinese-astrology-skill
npm install
npm start
# Server runs at http://localhost:3000/mcpTools
1. getBaziChart — BaZi Chart Calculation (八字排盘)
Calculate a complete Four Pillars of Destiny chart from birth datetime.
Input:
{
"solarDatetime": "2000-01-15T12:00:00+08:00",
"gender": 1
}Returns: Complete BaZi chart including:
Four Pillars (年柱/月柱/日柱/时柱) with Heavenly Stems & Earthly Branches
Five Elements (五行) for each position
Ten Gods (十神) relationships
Hidden Stems (藏干) — main, middle, and residual qi
Nayin (纳音), Void (空亡), Terrain (星运)
Decade Fortune (大运) — 10 periods with start ages
Gods & Spirits (神煞) for all four pillars
Branch Relations (刑冲合会) — clashes, combinations, penalties
2. findBirthDates — Reverse BaZi Lookup (八字反查)
Find all possible birth dates (from 1700 to present) that match a given BaZi string.
Input:
{
"bazi": "戊寅 己未 己卯 辛未"
}Returns: Array of matching solar datetimes.
3. getAlmanac — Chinese Almanac (黄历)
Get Chinese almanac information for any date.
Input:
{
"solarDatetime": "2026-04-06T00:00:00+08:00"
}Returns: Lunar date, zodiac, Nayin, solar terms, 28 mansions, Peng Zu taboos, directional gods (Joy/Yang Noble/Yin Noble/Mascot/Wealth), auspicious & inauspicious activities, clash info.
4. calculateBoneWeight — Bone Weight Fortune (秤骨算命) ⭐
Calculate bone weight fortune using Yuan Tiangang's ancient Tang Dynasty method (c. 600 CE).
Input:
{
"solarDatetime": "1990-06-15T14:00:00+08:00"
}Returns:
{
"totalWeight": 4.8,
"unit": "两 (liǎng)",
"percentile": 54,
"breakdown": {
"year": { "ganzhi": "庚午", "weight": 0.9 },
"month": { "lunarMonth": 5, "weight": 0.5 },
"day": { "lunarDay": 23, "weight": 0.8 },
"hour": { "earthBranch": "未", "weight": 0.8 }
},
"poem": "初年运道未曾亨...",
"interpretation": "Late success through independence..."
}Weight ranges from 2.1 to 7.2 liǎng across 52 destiny types. Learn more about bone weight fortune →
Use Cases
AI Chatbots — Give your AI assistant accurate BaZi reading capabilities
Fortune Telling Apps — Build Chinese astrology features into your product
Calendar Apps — Add Chinese almanac and auspicious date lookup
Research — Explore traditional Chinese metaphysics computationally
Tech Stack
tyme4ts — Chinese calendar calculation engine
cantian-tymext — Extended BaZi analysis
MCP SDK — Model Context Protocol for AI integration
Related
Ba-Zi.ai — Free AI BaZi calculator with deep analysis reports
BaZi Calculator — Generate your Four Pillars chart in 30 seconds
Bone Weight Calculator — Free online Yuan Tiangang bone weight fortune
BaZi Compatibility — Check relationship compatibility with BaZi
What is BaZi? — Complete guide to Four Pillars of Destiny
Roadmap
v1.0 — BaZi chart, reverse lookup, almanac, bone weight
v2.0 — Qi Men Dun Jia (奇门遁甲)
v3.0 — Zi Wei Dou Shu (紫微斗数)
License
MIT — see LICENSE
Built with ❤️ by Ba-Zi.ai — AI-powered Chinese astrology for everyone.
Available Tools
4 toolscalculateBoneWeightB
Calculate bone weight fortune (秤骨算命) using Yuan Tiangang's ancient Tang Dynasty method. Assigns weight values to birth year/month/day/hour and returns a destiny poem with interpretation. This tool is exclusive to chinese-astrology-skill. 袁天罡秤骨算命法,根据出生时间计算骨重与命运诗。
| Name | Required | Description | Default |
|---|---|---|---|
| solarDatetime | Yes | Birth datetime in ISO format, e.g. "1990-06-15T14:00:00+08:00". 公历出生时间。 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose the computational model (weights assigned to birth year/month/day/hour) and the return shape (destiny poem with interpretation), but says nothing about determinism, calendar conversion assumptions, or whether the input timezone matters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The English sentence is well front-loaded, but the Chinese sentence restates the same content in full, and the 'exclusive to chinese-astrology-skill' claim adds no actionable information. Roughly a third of the text is redundant, though total length stays modest.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, no-output-schema tool, the description covers what goes in, what computation happens, and what comes back (poem plus interpretation), so an agent has enough to call it correctly. It falls short only on edge-case behavior such as solar/lunar handling and timezone expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single solarDatetime parameter, so the schema already carries the format and example. The description adds only that the datetime is decomposed into year/month/day/hour weights, which is marginal semantic value. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb+resource (calculate bone weight fortune) and identifies the underlying method (Yuan Tiangang's Tang Dynasty 秤骨算命), which is enough to separate it from getBaziChart or getAlmanac. However, it never explicitly contrasts itself with those siblings, so the differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context (you want a bone-weight fortune rather than a Bazi chart or almanac), but there is no explicit when-to-use, when-not-to-use, or named alternative. The 'exclusive to chinese-astrology-skill' note is a namespace remark, not routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
findBirthDatesA
Find possible birth dates from a BaZi string. Returns all matching solar datetimes from 1700 to present. 根据八字反查公历出生时间。
| Name | Required | Description | Default |
|---|---|---|---|
| bazi | Yes | BaZi string (space-separated four pillars), e.g. "戊寅 己未 己卯 辛未". 八字(空格分隔四柱)。 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the search range (1700 to present) and that all matching solar datetimes are returned. It says nothing about cardinality of results, ordering, ambiguity handling, or performance limits, which matter for a reverse-lookup that can be one-to-many.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core action and the return behavior. The Chinese sentence duplicates the English content, adding length, but serves a plausible bilingual-audience purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with no output schema, the description covers purpose, input form, result content, and temporal range. It stops short of noting that multiple dates may match or how results are ordered, a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single bazi parameter is already documented with format and an example, so the schema does the heavy lifting. The description adds no further format or parsing semantics beyond what the schema provides; baseline 3 applies for a 1-param tool with full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (find) and resource (possible birth dates) plus the input (a BaZi string), which reads clearly as the inverse of the sibling getBaziChart. It does not name the sibling, so the distinction must be inferred from the direction of the lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by 'from a BaZi string' (use this when you have pillars and want dates), but there is no explicit when-to-use statement, no exclusion, and no reference to getBaziChart as the opposite-direction alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getAlmanacA
Get Chinese almanac (黄历) for a specific date. Returns lunar date, auspicious/inauspicious activities, directional gods, and more. 获取指定日期的黄历信息。
| Name | Required | Description | Default |
|---|---|---|---|
| solarDatetime | No | Date in ISO format. Defaults to today (China time). 公历日期,默认今天。 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It usefully enumerates the return payload (lunar date, auspicious/inauspicious activities, directional gods), which signals a read-only lookup, but says nothing about permissions, rate limits, or data source/accuracy caveats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the core purpose front-loaded and return contents enumerated. The bilingual repetition of the same sentence adds length without new information, though it does serve non-English callers.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must describe returns, and it does list the key fields while noting 'and more'. For a simple zero-required-param lookup this is nearly complete; only the exact payload shape remains unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single solarDatetime parameter is fully documented in the schema (ISO format, defaults to today China time). The description only refers to 'a specific date', adding no format or default semantics beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Get) and resource (Chinese almanac/黄历) scoped to a date, plus an outline of the return contents. An agent can distinguish this from the numeric/chart siblings (getBaziChart, calculateBoneWeight), though the description never names or contrasts them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the resource itself — fetch almanac data for a given day — but there is no explicit when-to-use, when-not-to-use, or routing to alternatives among the sibling tools. Adequate but leaves selection entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getBaziChartA
Calculate a complete BaZi (Four Pillars of Destiny) chart from birth datetime. Returns the eight characters, Five Elements, Ten Gods, Hidden Stems, Decade Fortune, and more. 根据出生时间计算完整八字命盘。
| Name | Required | Description | Default |
|---|---|---|---|
| gender | Yes | 0 = female, 1 = male. 0=女,1=男。 | |
| lunarDatetime | No | Lunar birth datetime, e.g. "2000-5-5 12:00:00". 农历出生时间。 | |
| solarDatetime | No | Birth datetime in ISO format, e.g. "2000-01-15T12:00:00+08:00". 公历出生时间。 | |
| eightCharProviderSect | No | Late Zi hour config. 1 = next day, 2 = same day (default). 早晚子时:1=明天,2=当天。 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It frames the tool as a computation and lists what is returned, which conveys read-only, non-mutating behavior, but says nothing about permission needs, latency, or whether historical/future dates are restricted or error out.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded: the verb and resource come first, the output enumeration second. The bilingual duplication of the same sentence adds length without new information, but there is no filler beyond that.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so listing the returned fields (Ten Gods, Hidden Stems, Decade Fortune) is genuinely useful compensation and tells the agent what to surface. The remaining gap is input-side: it never clarifies which datetime field to supply or why gender is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and every parameter carries its own bilingual description, so the schema does the heavy lifting. The description adds no extra meaning — it does not explain the required gender field, the lunar-vs-solar choice, or the eightCharProviderSect default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Calculate a complete BaZi chart') and enumerates the outputs (eight characters, Five Elements, Ten Gods, Hidden Stems, Decade Fortune). Nothing about it overlaps with findBirthDates, getAlmanac, or calculateBoneWeight, so an agent can discriminate it without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'from birth datetime' implies the input context but never states when to prefer this over the sibling fortune/almanac tools, nor how to choose between lunarDatetime and solarDatetime — a central decision for this tool. Usage is only inferable, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
v1.0.1- First observed
calculateBoneWeight - First observed
findBirthDates - First observed
getAlmanac - First observed
getBaziChart
TDQS
Scored across 4 tools
Each tool targets a distinct method: chart casting (getBaziChart), reverse lookup (findBirthDates), almanac (getAlmanac), and bone-weight divination (calculateBoneWeight). The main risk is getBaziChart vs calculateBoneWeight, which both consume a birth datetime and output a fortune reading, but their descriptions clearly separate the BaZi method from the Yuan Tiangang method.
All names use consistent camelCase with a leading verb (getBaziChart, findBirthDates, getAlmanac, calculateBoneWeight). The verbs vary (get/find/calculate) but each fits its operation, so the minor deviation is readable and predictable rather than chaotic.
Four tools is lean but well-scoped for a focused astrology skill, with each tool clearly earning its place. It sits at the thin edge but does not feel arbitrarily padded or truncated.
The surface covers the core domain: casting a chart, reverse-resolving a chart to dates, daily almanac, and bone-weight divination. Common extras like zodiac compatibility or annual fortune analysis are absent, but the primary BaZi/almanac workflows have no dead ends.
Maintenance
Related MCP Connectors
BaZi MCP gateway: 14 tools (6 fortune / 5 forum / 3 meta). API key required. Entertainment only.
Free BaZi, I Ching, tarot, Zi Wei and bilingual learning tools with transparent methods. No API key.
Generate BaZi charts from birth details. Explore Four Pillars, solar terms, and Luck Pillars for d…
BaZi four pillars, Chinese zodiac, lunisolar calendar and almanac days for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides professional Chinese astrology calculations including Four Pillars, Five Elements, zodiac signs, and lunar calendar details. It allows users to perform accurate Bazi analysis with global timezone support directly within MCP-compatible clients.9 npm10MIT
- FlicenseNot gradedqualityBmaintenanceEnables traditional Chinese metaphysics tools like Bazi, Ziwei, and Qimen via MCP, integrating AI analysis for divination and fortune-telling.641-
- AlicenseAqualityAmaintenanceProvides traditional Chinese astrology (Bazi, Ziwei) and divination (Liuyao, Meihua, Qimen, etc.) calculations as MCP tools for AI assistants.18133 npm118Apache 2.0
- AlicenseAqualityCmaintenanceProvides Chinese metaphysical tools (bazi, qimen, five elements) as MCP tools for AI agents to give personalized advice on timing, compatibility, and daily energy.573 npm1MIT