FateStar Ziwei

A Zi Wei-focused hosted MCP for AI agents. One URL; no local server, package install, account, or API key for natal charts and six transit levels. Also available as an Agent Skill and REST API.

简体中文

Natal charts and six-level transits work anonymously. The optional Zheng Da Qian reading uses a FateStar API key and credits.

Try it now

Open a live anonymous chart response. No account or API key is required. Selected fields from that response:

Solar 1990-7-23 | Lunar 一九九〇年六月初二
Five-elements class 土五局 | Life ruler 文曲 | Body ruler 火星
Life palace 己卯 | 廉贞 (平), 破军 (陷)
12 palaces | 5 detected patterns | 4 natal transformations

After installing the Skill or connecting the MCP endpoint, tell your agent:

Create a Zi Wei Dou Shu chart for a man born on July 23, 1990 at 8:00 AM, then show his 2026 transits.

The agent calls FateStar and returns:

• a natal chart with 12 palaces, stars, brightness, and Four Transformations;
• true-solar-time correction when longitude and timezone are supplied;
• decade, minor-cycle, annual, monthly, daily, and hourly transits;
• an optional Zheng Da Qian reading when a valid key and credits are available.

If the live result is useful, star the repository. It helps other agent developers find the free endpoint.

Why FateStar

FateStar is deliberately narrow: it makes Zi Wei chart data easy to use from an AI agent without operating a local astrology server.

These are different deployment choices, not a claim that one school or engine is universally more accurate.

Quick start

Agent Skill

GitHub CLI 2.90 or newer installs the Skill into Codex, Claude Code, Cursor, and many other agents.

# Codex
gh skill install LouisLin0723/fatestar-ziwei ziwei-paipan --agent codex --scope user

# Claude Code
gh skill install LouisLin0723/fatestar-ziwei ziwei-paipan --agent claude-code --scope user

# Cursor
gh skill install LouisLin0723/fatestar-ziwei ziwei-paipan --agent cursor --scope user

Restart the agent, then ask it to create a Zi Wei Dou Shu chart. The canonical Skill is in skills/ziwei-paipan.

If your GitHub CLI is older, upgrade it or copy the skills/ziwei-paipan directory into your agent's Skill directory.

Hosted MCP

No local server is required. Add the remote endpoint to a client that supports Streamable HTTP:

{
  "mcpServers": {
    "fatestar-ziwei": {
      "url": "https://www.fatestar.top/api/mcp"
    }
  }
}

The endpoint exposes ziwei_chart, ziwei_transits, and ziwei_reading. The first two tools are free and anonymous.

tools/list declares an outputSchema and behavior annotations for every tool. Successful calls return both native structuredContent and legacy JSON text, so newer agents can consume typed fields while older clients keep working.

The server is listed in the official MCP Registry as io.github.LouisLin0723/fatestar-ziwei.

REST API

Run a free chart request without an account:

curl "https://www.fatestar.top/api/ziwei?year=1990&month=7&day=23&hour=8&gender=male"

Full API and client documentation: fatestar.top/docs

Choose an integration

All three routes use the same FateStar engine. Pick the interface that fits your client.

Capabilities

The Skill ships Python, Node.js, PowerShell, and Bash clients. Python and Node.js use their standard libraries and require no package install.

CLI examples

Run these commands from the installed ziwei-paipan Skill directory:

# Free natal chart
python scripts/ziwei_cli.py chart \
  --year 1990 --month 7 --day 23 --hour 8 --gender male

# Free 2026 transits
python scripts/ziwei_cli.py transits \
  --year 1990 --month 7 --day 23 --hour 8 --gender male \
  --target-year 2026

# Hosted reading, requires FATESTAR_API_KEY
python scripts/ziwei_cli.py reading \
  --year 1990 --month 7 --day 23 --hour 8 --gender male \
  --question "Should I change jobs this year?"

Use python scripts/ziwei_cli.py doc for the offline interface reference. Equivalent Node.js, PowerShell, and Bash clients are in the same directory.

API key and billing

chart and transits are free with or without a key. A key only attributes those free calls to your account.

reading requires an FSFSKey and may consume credits. Create a key in the FateStar developer center. Store it outside source control:

export FATESTAR_API_KEY="FSFSKey_your_key"

For MCP clients, send Authorization: Bearer FSFSKey_your_key only when you want to use ziwei_reading. Never commit a real key or paste it into an issue.

Repository layout

skills/ziwei-paipan/
├── SKILL.md
├── agents/openai.yaml
├── scripts/
│   ├── ziwei_cli.py
│   ├── ziwei_cli.js
│   ├── ziwei_cli.ps1
│   ├── ziwei_cli.sh
│   └── shared/

The root server.json describes the hosted endpoint using the official MCP Registry schema.

Development

python skills/ziwei-paipan/scripts/generate.py --check
python tests/live_contract_check.py
python skills/ziwei-paipan/scripts/ziwei_cli.py doc
node skills/ziwei-paipan/scripts/ziwei_cli.js doc
powershell -ExecutionPolicy Bypass -File skills/ziwei-paipan/scripts/ziwei_cli.ps1 doc
bash skills/ziwei-paipan/scripts/ziwei_cli.sh doc

The four clients share generated constants and an offline interface spec. Edit the shared files first, run generate.py, then run the checks above. The broader compatibility matrix is in docs/TEST_PLAN.md. The exact hosted MCP assertions and their limits are documented in docs/VERIFICATION.md.

Open-source boundary

This repository contains the Agent Skill, four thin clients, integration metadata, and public documentation. FateStar's server implementation, private prompts, Zheng Da Qian training data, retrieval corpus, evaluation sets, and billing controls are not included.

The repository code is MIT licensed. FateStar's brand, hosted service, and private knowledge assets remain proprietary.

Contributing

Bug reports, client examples, and compatibility fixes are welcome. Read CONTRIBUTING.md before opening a pull request. Security reports belong in SECURITY.md, not a public issue.