BaZi True Solar Time MCP

Deterministic true solar time conversion for BaZi and calendrical workflows.

Documentation

True Solar Time MCP Server

MCP server npm package License: MIT AllMCPs Verified

An MCP server for deterministic true solar time conversion from a local civil time, IANA timezone, and longitude.

Built for reproducible calendrical, astronomy, BaZi, and Four Pillars workflows. The server is intentionally narrow: it does not geocode an address, call a language model, persist birth data, or generate fortune-telling text.

Why this is useful

  • No address lookup. Pass the timezone and coordinates you already trust; there is no hidden geocoding request.
  • Transparent correction. The result separates longitude correction, equation of time, DST correction, UTC, and date rollover.
  • MCP-native. One read-only tool works with Claude Desktop, Cursor, Codex, and other MCP clients.
  • Privacy-friendly. Calculation is local to the process running the server.

Tool

calculate_true_solar_time

Input:

{
  "date": "1990-05-20",
  "time": "14:30",
  "timezone": "Asia/Shanghai",
  "longitude": 104.0668,
  "latitude": 30.5728
}

longitude is required and uses decimal degrees with east positive. latitude is optional and is retained for traceability; the correction is driven by longitude, the time-zone offset, and the equation of time.

The result includes the civil time, UTC instant, corrected true solar time, longitude correction, equation-of-time correction, DST correction, date shifts, warnings, and a confidence label.

Quick start

Run directly from npm:

npx -y bazi-true-solar-time-mcp

Or inspect and build from source:

git clone https://github.com/cdaily1995-create/true-solar-time-mcp.git
cd true-solar-time-mcp
pnpm install
pnpm build
node dist/server.js

MCP client configuration:

{
  "mcpServers": {
    "true-solar-time": {
      "command": "npx",
      "args": ["-y", "bazi-true-solar-time-mcp"]
    }
  }
}

Example

calculate_true_solar_time {
  "date": "2002-07-07",
  "time": "05:05",
  "timezone": "America/Los_Angeles",
  "longitude": -118.2437,
  "latitude": 34.0522
}

The response includes a versioned engineVersion, the UTC instant, the corrected local apparent solar time, each correction component, warnings, and confidence.

Input contract

FieldRequiredDescription
dateyesLocal civil date in YYYY-MM-DD.
timeyesLocal civil time in HH:mm.
timezoneyesIANA identifier such as Asia/Shanghai or America/Los_Angeles.
longitudeyesDecimal degrees, east positive, from -180 to 180.
latitudenoDecimal degrees, from -90 to 90; retained for traceability.

Links

Search-friendly description

This project is a true solar time calculator for birth-time normalization. It explains how civil time, longitude, historical time zones, daylight-saving offsets, and the equation of time affect local apparent solar time. It is useful for BaZi, Four Pillars, traditional calendar, astronomy, and time-normalization workflows where reproducible numeric output is more important than interpretation.

Privacy and scope

The server accepts coordinates and time-zone identifiers only. It has no address search, analytics, database, account, payment, or external API requirement. Results are calculated locally by the process running the MCP server.

This is a time conversion utility, not scientific proof of any astrological interpretation and not a prediction service.

License

MIT