Unified Reading

unified-reading

SDK, CLI and stdio MCP server for the public Unified Reading API. Give it a birth date and it returns the Life Path number, the Western Sun sign and the Chinese zodiac animal. It also covers the 1924-2044 Lunar New Year table. There is no API key and nothing is stored.

Send only birth dates, never names, birth times or places. The combined personal reading is at unifiedreading.com.

CLI

npx unified-reading profile 1990-07-14

1990-07-14

Life Path 4 The Builder Sun sign ♋ Cancer, decan 3 (Water, Cardinal, ruled by Moon) Chinese Yang Metal Horse

Add --json to any command for the raw API response. --base-url points the CLI at another origin.

MCP server

unified-reading mcp runs a stdio MCP server that forwards to the remote server at https://unifiedreading.com/mcp. It is for MCP clients that only launch local commands:

{ "mcpServers": { "unified-reading": { "command": "npx", "args": ["-y", "unified-reading", "mcp"] } } }

The server has tools for reading options, the birth date profile (with an MCP Apps card) and Chinese zodiac years. It is listed in the official MCP registry as com.unifiedreading/unified-reading.

SDK

Needs Node 18 or later, or any runtime with fetch.

import { UnifiedReading, UnifiedReadingError } from "unified-reading";

const client = new UnifiedReading();

const profile = await client.profile("1990-07-14"); console.log(profile.lifePath.number, profile.sunSign.sign, profile.chineseZodiac.animal); // 4 Cancer Horse

const results = await client.profiles(["1990-07-14", "1990-01-20"], { idempotencyKey: crypto.randomUUID() });

for await (const year of client.allChineseZodiacYears()) { console.log(year.year, year.animal, year.starts, year.ends); }

try { await client.profile("1990-02-30"); } catch (error) { if (error instanceof UnifiedReadingError) console.log(error.code, error.hint); // invalid_date ... }

Dates can be YYYY-MM-DD strings or Date objects; a Date is sent as its local calendar date. Errors throw UnifiedReadingError, which carries status, code, hint and retryAfter. The API allows 10 requests per minute per IP.

Links

• API guide: https://unifiedreading.com/docs
• OpenAPI spec: https://unifiedreading.com/openapi.json
• MCP server (same calculations for AI agents): https://unifiedreading.com/mcp
• Source: https://github.com/emrecolako/unified-reading/tree/main/sdk
• Bug reports: https://github.com/emrecolako/unified-reading/issues (no personal data), or hello@unifiedreading.com