开发者

把万年历的能力接进你的脚本或 AI 助手：农历换算、黄历宜忌、二十四节气、法定节假日与工作日推算。提供 REST 与 MCP 两种接法，按调用次数扣积分。

三步接上

微信扫码登录，到充值买一包积分。
在 API 令牌创建一把密钥，勾上需要的权限。明文只显示一次，当场复制走。
请求时带上 Authorization: Bearer <你的密钥>。

REST 接口

一个入口 GET /api/v1/calendar，用 op 选能力。

op	参数	说明
day	date=YYYY-MM-DD	某天的农历、干支、生肖、星座、节气、节日、法定节假日与黄历宜忌
lunar2solar	year&month&day&isLeap	农历转公历
solarTerms	year	某年的二十四节气及公历日期
workdays	from&to	区间内的工作日数（扣周末与法定节假日、算回调休）
nthWorkday	from&n	从某天起第 N 个工作日，n 可为负

curl -H "Authorization: Bearer ha_pat_xxx" \
  "https://handapp.com/api/v1/calendar?op=day&date=2026-02-17"

# 明年春节是哪天
curl -H "Authorization: Bearer ha_pat_xxx" \
  "https://handapp.com/api/v1/calendar?op=lunar2solar&year=2027&month=1&day=1"

# 这个月还有几个工作日
curl -H "Authorization: Bearer ha_pat_xxx" \
  "https://handapp.com/api/v1/calendar?op=workdays&from=2026-08-16&to=2026-08-31"

每个响应都带两个头：x-credits-charged（这次扣了多少）与 x-credits-balance（还剩多少）。不用另外查余额。

MCP

端点 https://handapp.com/api/mcp，Streamable HTTP 传输。在 Claude Desktop、Claude Code 或任何支持 MCP 的客户端里这样配：

{
  "mcpServers": {
    "handapp-calendar": {
      "url": "https://handapp.com/api/mcp",
      "headers": { "Authorization": "Bearer ha_pat_xxx" }
    }
  }
}

工具	用途
get_day_info	查某天的农历与黄历信息
lunar_to_solar	农历转公历
get_solar_terms	查某年的二十四节气
count_workdays	算区间内的工作日数
add_workdays	推算第 N 个工作日

握手（initialize）与列工具（tools/list）不需要密钥、也不扣积分 —— 客户端每次连接都要问一遍，为这个收费没有道理，而且拦下来会让「配置到底对不对」很难排查。真正取数据的 tools/call 才校验密钥并扣费。

权限与计费

权限	单次积分	覆盖
calendar:read	1	日历公开数据与 MCP 工具
me:read	1	读你自己的备注 / 标记 / 倒数日 / 常用网址
me:write	1	写你自己的那些数据

参数写错也会扣费。鉴权与扣费在业务逻辑之前完成 —— 否则一个坏掉的脚本可以无限次免费打这个接口探参数。调试时先用少量请求确认参数，再放开跑。
积分不足返回 402，响应头带上当前余额。
密钥无效或过期返回 401，权限不够返回 403。这两种都不扣费。

几件要留意的

密钥就是钱。拿到它就能花掉你的积分。别提交进仓库、别写进前端代码。怀疑泄漏立刻吊销，即时生效。
农历覆盖 1900–2100 年，超出范围返回 400。
法定节假日与调休目前覆盖 2024–2026，其余年份只按周末算，工作日数会偏多。国务院每年通知发布后我们会更新。
黄历宜忌是传统民俗的现代化转译，仅供参考与文化娱乐，别拿它做决策 —— 详见《用户协议》第 3 条。
接口路径、参数与价格可能调整，重大变更会提前在本页公布。