timemap-mcp

Chinese metaphysics calculations for AI agents — BaZi, Tong Shu, Feng Shui, and more.

<!-- Badges — uncomment after PyPI publish -->

An MCP (Model Context Protocol) server that gives AI agents access to accurate Chinese metaphysics calculations. Built on a verified engine with 740+ tests checked against Joey Yap reference data.

About

I discovered BaZi in 2017 and approached it with healthy skepticism — it wasn't the first system of correspondences I'd studied. But this one stayed with me.

Over the years I've studied under Master Joey Yap through courses, seminars, his Telegram community, and many books. As a developer, I naturally started building tools — small "clocks" that map the cyclic energy movements described in Chinese metaphysics.

timemap-mcp is born from those years of study and building. I wanted to make these calculations accessible to everyone through AI, with the accuracy that practitioners expect. A full interactive app (TimeMap) is on the way — this MCP server is the engine that powers it, now available for any AI agent to use.

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "timemap": {
      "command": "uvx",
      "args": ["timemap-mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "timemap": {
      "command": "uvx",
      "args": ["timemap-mcp"]
    }
  }
}

That's it. No API keys, no config needed.

Note: The first run downloads the DE421 ephemeris file (~31 MB) for precise solar term calculations. This is a one-time download cached in ~/.skyfield/.

Tools

Tool	Description	Natal needed?
get_natal_chart	Complete BaZi chart — Four Pillars, Luck Pillars, Life Gua, 10 Gods, auxiliary stars	Yes
get_daily_pillars	Year, Month, Day pillars for any date	No
get_day_quality	Tong Shu indicators — Day Officer, 28 Constellation, Flying Star	No
get_daily_interactions	Check natal clashes, combinations, and breakers for a date	Yes
get_hourly_pillars	12 two-hour energy blocks for any day	No
get_luck_pillars	10-year Luck Pillar timeline (decades of fortune)	Yes
lookup_hexagram	Xuan Kong Da Gua hexagram by stem-branch pair	No
get_solar_term	Exact date of any of the 24 solar terms	No

Example Prompts

Try asking your AI agent:

• "Calculate my BaZi chart. I was born January 26, 1994 at 7:11 AM, male."
• "What's the day quality for today?"
• "Show me the hourly pillars for tomorrow."
• "What are my luck pillars? Born March 15, 1985 at 10:30 AM, female."
• "Look up the hexagram for Ren Zi."
• "When is Lichun (Start of Spring) in 2026?"
• "Check if today has any clashes with my natal chart."

Input Formats

• Dates: ISO 8601 — 1994-01-26
• Times: 24-hour local time — 07:11
• Gender: male or female
• Stems: Chinese (壬), pinyin (Ren), or index (8)
• Branches: Chinese (子), pinyin (Zi), animal (Rat), or index (0)
• Timezone (optional): IANA format — Asia/Kuala_Lumpur, Europe/Bucharest

Engine Accuracy

The calculation engine behind this server is not a toy:

• 740+ automated tests covering every module
• Verified against Joey Yap's Power Planner — pillar characters, Day Officers, 10 Gods mappings
• Solar term boundaries computed via NASA JPL DE421 ephemeris (not table approximations)
• Month boundaries follow Jie Qi (solar terms), not Gregorian dates — February pillar may start Feb 3 or 4 depending on the year

Roadmap

The free tier covers the fundamentals. Coming in v2 (premium):

• 10 Gods Strength — proprietary percentage algorithm (reverse-engineered, MSE=0.5)
• Daily Score (0-100) — composite score with transparent 6-factor breakdown
• Qi Men Dun Jia — destiny palace, annual chart, hourly interpretation
• Monthly Energy — 10 Gods deltas, life area radar, emotional profiling
• Daily Briefing — complete orchestrated daily digest

Development

git clone https://github.com/cnick26/timemap-mcp.git
cd timemap-mcp
python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"   # Windows
# or: .venv/bin/pip install -e ".[dev]"  # Linux/macOS
pytest -q                                # 740+ tests

Syncing the engine from TimeMap

python scripts/sync_engine.py --source ../TimeMap/backend/app/engine
pytest -q  # Verify everything still passes

Support

If this project helps you, consider:

• Starring the repo
• Buy Me a Coffee

License

MIT

---

Built with care, verified with rigor, shared with humility.