mcpField
C
calendar-api

calendar-api

github.com/wmy2981Other153 installsUpdated 5w ago
Repository

About calendar-api

calendar-api is a skill for querying traditional Chinese calendar details for a date through the 接口盒子 API. It defaults to today and formats returned calendar fields for display, with an option to output raw JSON.

Key features

  1. 01Queries the 接口盒子 API for calendar data
  2. 02Defaults to today's date
  3. 03Accepts a specific date as input
  4. 04Displays non-empty fields by category
  5. 05Offers raw JSON output

Use cases

  1. 01Checking traditional calendar details for today
  2. 02Looking up auspicious and inauspicious details for a date
  3. 03Inspecting API output as JSON

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/wmy2981/skills --skill calendar-api

After installing, type/calendar-apiin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

.claude-plugin/
plugin.json
references/
api_doc.md
scripts/
.env.example
getzdday.py

Details

From the project README

Chinese Calendar Query

Queries the 接口盒子 API (API ID: 278) to retrieve comprehensive traditional Chinese calendar (黄历) information for any date.

Execution Rule

Run the user's requested command directly without pre-checking dependencies, environment variables, or configuration. If something is wrong, the script will fail with a clear error — check and fix only then.

Environment Variables

VariableDescription
JKHZ_ID接口盒子 (apihz.cn) user ID
JKHZ_KEY接口盒子 API key

The script loads these from ~/.wmyskills/.env (shared across skills) automatically; a scripts/.env in the script directory takes priority if present. Use scripts/.env.example as the template — add the variables to ~/.wmyskills/.env, never overwriting an existing file.

Requirements

pip install python-dotenv tzdata

Usage

Script: scripts/getzdday.py

Query today
python scripts/getzdday.py
Query a specific date
python scripts/getzdday.py 2025-06-05
Output raw JSON (debugging)
python scripts/getzdday.py 2025-06-05 --json

Output Categories

The script organizes returned data into these categories:

CategoryFields
📆 Gregorian Calendar (公历)Year, month, day, weekday, leap year
🌙 Lunar Calendar (农历)Lunar year, month, day
🎊 Festivals (节日)Solar festivals, lunar festivals
⭐ Constellation & Zodiac (星座与生肖)Constellation, Chinese zodiac, daily zodiac
📜 Stems & Branches (干支)Year/month/day Ganzhi, day Nayin
🌿 Solar Terms & Phenology (节气与物候)Solar term, description, Wuhou, Shujiu, Sanfu
☯ Auspicious/Inauspicious (宜忌)Yi (宜), Ji (忌), auspicious/inauspicious gods
🧭 Directions (方位)Xi (喜), Cai (财), Fu (福), Gui (贵) spirit directions
⚠️ Clash & Sha (冲煞)Xiangchong, Richtungschong, Tian Shen, Huang/Hei Dao
🔢 Star & Spirit (值星与神煞)Zhi Xing (12 value stars), 12 spirits, Liuyao, moon phase
🌟 Mansions (星宿)28 mansions, animal, luck, 7 luminaries, 4 palaces, 4 symbols
📖 Peng Zu & Fetal God (彭祖与胎神)Peng Zu's hundred taboos, fetal god direction, Taisui
📅 Buddhist/Taoist Calendar (佛道历)Buddhist calendar, Taoist calendar, Islamic calendar
📊 Other (其他)Wuxing (5 elements), Julian day, 9 stars, season

Notes

  • Defaults to today's date (Asia/Shanghai timezone)
  • API year range: 1800 to next year
  • Formatted output is suitable for direct display; --json for debugging
  • The API may return different fields per date; the script dynamically displays all non-empty fields
  • Match the user's language. The output language MUST match the language of the user's question. If the user asks in Chinese, output all category labels and descriptions in Chinese; if in English, output in English.

Comments

Markdown supported