openworkdays

OpenWorkdays

无需注册的工作日日期运算 API。无需账户，无需 API 密钥——一个 GET 请求即可。

使用你自己的节假日列表，增加或减少工作日、计算两个日期之间的工作日数，或判断某个日期是否为工作日。纯 UTC 日期运算，以 JSON 返回。专为自主 AI Agent 打造，提供确定性的日期端点——Agent 无法找人代为注册，而大模型在日期运算方面的表现已被证实并不可靠。

在线服务：https://openworkdays.vercel.app

快速开始

curl "https://openworkdays.vercel.app/api/businessdays?start=2026-05-15&days=5"

示例响应：

{
  "mode": "add",
  "start": "2026-05-15",
  "days": 5,
  "result": "2026-05-22",
  "resultWeekday": "fri",
  "startIsBusinessDay": true,
  "weekend": ["sat", "sun"],
  "holidaysApplied": 0,
  "engine": "date-utc-v0.1",
  "computedAt": "2026-05-17T00:00:00.000Z"
}

任何错误都会以 JSON 返回，包含 error 键和相应的 HTTP 状态码（400 参数错误，429 请求频率受限，405 请求方法错误）。

三种模式

端点始终为 GET /api/businessdays。模式根据传入的参数推断。

add — 增加／减少工作日

参数：start=YYYY-MM-DD、days=N（整数，可用 +／-，|N| <= 10000），可选的 weekend=、可选的 holidays=。

curl "https://openworkdays.vercel.app/api/businessdays?start=2026-05-15&days=5"

N=0 时会原样返回 start（即使 start 本身不是工作日）。

diff — 计算两个日期之间的工作日数

参数：start=YYYY-MM-DD、end=YYYY-MM-DD，可选的 weekend=、可选的 holidays=。包含两个端点。如果 end < start，结果为负数。

curl "https://openworkdays.vercel.app/api/businessdays?start=2026-05-15&end=2026-06-15&holidays=2026-05-25"

is — 此日期是否为工作日？

参数：date=YYYY-MM-DD，可选的 weekend=、可选的 holidays=。

curl "https://openworkdays.vercel.app/api/businessdays?date=2026-05-16"

返回 isBusinessDay，以及值为 "weekend"、"holiday" 或 null 的 reason。

通用参数

• weekend（默认为 sat,sun）——逗号分隔的列表。标记不区分大小写，可使用 {sun,mon,tue,wed,thu,fri,sat} 中的值，也可使用 0-6 数字，其中 0=Sunday … 6=Saturday（与 JS getUTCDay() 一致）。不能将全部 7 天都设为周末。
• holidays ——以逗号分隔的 YYYY-MM-DD 日期列表，这些日期将视为非工作日（最多 1000 个）。严格校验。

错误

错误以 JSON 返回，并包含 error 键：

• 400 —— 参数无效／缺失（missing start、invalid days (must be integer)、invalid weekend token、invalid holiday date、invalid date、specify a mode（包含 usage 对象）等）
• 429 —— 请求频率受限（包含 Retry-After 标头和 retryAfterSec）
• 405 —— HTTP 请求方法错误（仅允许 GET／OPTIONS）

JavaScript

const base = "https://openworkdays.vercel.app";
const r = await fetch(
  base + "/api/businessdays?start=2026-05-15&days=5"
);
const out = await r.json(); // { mode:"add", result:"2026-05-22", resultWeekday:"fri", ... }

用作 MCP 工具（AI Agent / Claude / Cursor / 大模型客户端）

OpenWorkdays 也是一个远程 MCP 服务，因此 Agent 无需注册、API 密钥或 OAuth，即可将其作为工具调用。

• 端点：https://openworkdays.vercel.app/api/mcp
• 传输方式：无状态 Streamable HTTP（发送 POST JSON-RPC 2.0，接收单个 application/json 响应——无会话、无 SSE）
• 仅提供一个工具：businessdays——根据传入的参数推断模式（add／diff／is），返回与 REST 端点相同的 JSON（也会作为 structuredContent 返回）

将以下内容添加到任意 MCP 客户端配置中（Claude Desktop、Cursor 或任何支持 Streamable HTTP 传输方式的客户端）：

{ "mcpServers": { "openworkdays": { "url": "https://openworkdays.vercel.app/api/mcp" } } }

快速冒烟测试：

curl -s -X POST https://openworkdays.vercel.app/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"businessdays","arguments":{"start":"2026-05-15","days":5}}}'

通过 MCP 调用时，上游错误会作为包含 isError: true 的工具结果返回。

为什么

所有公开的工作日 API 都要求注册账户或提供 API 密钥：workingdays.org 仅供测试／需要订阅；API Ninjas 和 Holiday API 需要密钥；timeanddate 是一款售价 $299 的产品；RapidAPI 上的工作日 API 需要 RapidAPI 密钥；Microsoft 的 “Calculate Working Day” 连接器受 Power Platform 框架限制，且仅支持英国银行假日。OpenWorkdays 只需发送匿名 GET 请求——无需注册，无需密钥。这对自主 Agent 尤其有用，因为它们无法让人代为完成注册。而且，大模型在日期运算方面的表现已被证实并不可靠，因此 Agent 需要一个确定性的端点，而不是自行猜测。

局限

• 仅支持日期级别的纯 UTC 运算——不支持时分秒、夏令时或时区 （这些属于重复规则的范畴，特意不纳入 v0.1 的范围）。
• 仅支持调用方提供的节假日——没有内置的国家节假日 数据库。这是有意为之：我们不会在由资金雄厚的现有企业胜出的 7000 节假日数据库赛道上假装竞争。你可以传入 所需的 holidays= 列表。
• 尽力而为的实例级 IP 速率限制——这是防止滥用的软性措施，不作保证 （无服务器实例是临时的，且彼此不共享）。
• 采用 MIT 许可，可自托管——见下文。

自托管——无需依赖文件

整个 API 由两个独立、零依赖的 Node 无服务器函数构成： api/businessdays.js（REST）和 api/mcp.js （远程 MCP）。无需执行 npm install，完全没有依赖。将文件夹部署到 Vercel （自动检测 /api，无需配置），或将处理程序放入任何 Node 无服务器运行时。

git clone https://github.com/SolvoHQ/openworkdays
cd openworkdays
npx vercel --prod

许可证

MIT——见 LICENSE。