True Solar Time MCP Server
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
| Field | Required | Description |
|---|---|---|
date | yes | Local civil date in YYYY-MM-DD. |
time | yes | Local civil time in HH:mm. |
timezone | yes | IANA identifier such as Asia/Shanghai or America/Los_Angeles. |
longitude | yes | Decimal degrees, east positive, from -180 to 180. |
latitude | no | Decimal degrees, from -90 to 90; retained for traceability. |
Links
- BaZi Calculator — the public calculator project using this kind of time normalization.
- Four Pillars of Destiny guide — background on the chart context.
- What is a BaZi chart? — plain-language chart explanation.
- Four Pillars MCP Server — the companion deterministic chart calculator.
- npm package — installable stdio MCP server.
- MCP specification — protocol documentation.
- MCP TypeScript server SDK — server SDK used by this project.
- npm installation guide — package-manager reference.
- Full link inventory and method references.
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