FateStar Ziwei README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the FateStar Ziwei listing page.
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:
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.
| Choose | When it fits |
|---|---|
| FateStar | You want a hosted remote MCP now: one URL, anonymous free charting, six transit levels, native structured MCP output, and an official Registry listing. |
| Iztro | You need an open-source Zi Wei engine to embed, inspect, or modify inside your own application. |
| Taibu or Horosa Skill | You prefer broader multi-system or offline metaphysics tooling over a focused hosted Zi Wei endpoint. |
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.
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:
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:
Full API and client documentation: fatestar.top/docs
Choose an integration
| Integration | Best for | Install | Free charting |
|---|---|---|---|
| Agent Skill | Codex, Claude Code, Cursor, and other coding agents | gh skill install | Yes |
| Hosted MCP | MCP clients with remote HTTP support | One URL | Yes |
| REST API | Apps, scripts, and backend services | curl or HTTP client | Yes |
All three routes use the same FateStar engine. Pick the interface that fits your client.
Capabilities
| Capability | Cost | Notes |
|---|---|---|
| Natal chart | Free | Solar or lunar input, 12 palaces, 102 stars, brightness, Four Transformations |
| Six-level transits | Free | Decade, minor cycle, year, month, day, and hour |
| True solar time | Free | Enabled with longitude and timezone input |
| Zheng Da Qian reading | Credits | FateStar knowledge engine and hosted reading service |
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:
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:
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
The root server.json describes the hosted endpoint using the official MCP Registry schema.
Development
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.