Workday MCP Server

一个只读的 MCP 服务器，将 Workday HCM 数据——员工、组织、监管组织、地点、职位简介和成本中心——作为可供 LLM 调用的工具暴露出来，由 Workday REST API v1.0（即每个 Workday 租户中都存在的"Common"/Foundation 资源集）提供支持。

使用官方 mcp Python SDK 构建，采用其 Streamable HTTP 传输，因此它可以作为 Google Cloud Run 上的普通无状态 HTTP 服务运行。

范围

Workday 现实中的 API 体系被拆分到许多独立版本化的 REST API 系列中（Common、Staffing、Absence Management、Compensation、Recruiting、Payroll、Talent 等）。本项目实现了 Common v1 资源，这些资源用途最广泛、只读，并且在每个租户中都存在：

所有工具均为只读（仅 GET 请求）。

要添加另一个 Workday API 系列（例如 Absence Management），请在 tools.py 中添加一个新的 @mcp.tool() 函数，该函数使用适当的路径调用 client.get(...)——workday_client.py 中的认证、错误处理和分页机制已经在所有工具之间共享。请注意，某些 Workday API 系列采用不同的版本化方式（例如 /ccx/api/staffing/v6/... 或 /ccx/api/absenceManagement/v2/...）；如果你要针对这些 API 添加工具，请通过额外的 base-URL 辅助函数扩展 WorkdayClient，而不是在 tools.py 中硬编码路径。

Related MCP server: Joule HR MCP Server

文件

server.py           MCP server entrypoint (FastMCP + Streamable HTTP transport)
tools.py            Tool definitions: params, docstrings, JSON -> summary text
workday_client.py   Workday REST client: OAuth2 auth, requests, error handling
requirements.txt    Pinned dependencies
Dockerfile          Slim, non-root container image for Cloud Run

身份验证

服务器使用 OAuth2 客户端凭据授权向 Workday 进行身份验证，对应端点如下：

{WORKDAY_HOST}/ccx/oauth2/{WORKDAY_TENANT}/token

这需要一个 Workday 注册 API 客户端（Registered API Client，即集成系统用户），要求其已启用 API 访问权限，并且对你想要查询的域（Worker Data、Organization Data 等）具有读访问权限。在 Workday 的 System → API Clients 下完成设置，并为生成的集成系统用户授予相应的安全组访问权限——这是 Workday 管理员的任务，不是此代码能替你完成的事情。

必需的环境变量

可选：

授权类型：客户端凭据与授权码

此客户端仅实现了客户端凭据授权（Client Credentials Grant，2-legged，机器对机器，无需用户登录）——它使用 grant_type=client_credentials 以及你的客户端 ID/密钥向令牌端点发送 POST 请求，完全不会触及授权端点。

如果你的 Workday API 客户端仅注册为授权码授权（Authorization Code Grant）（请在 Workday 中检查 System → API Clients——查看"Authentication Grant Type"字段以及是否设置了 Redirect URI），那么无论客户端 ID/密钥多么正确，client_credentials 令牌请求都会被以 401 拒绝。该流程需要通过授权端点进行一次性的交互式登录才能获得刷新令牌，这是另一个（更大的）集成工程——如果你需要这种方案，请告诉我们。

如果你收到 401，并且不确定启用了哪种授权类型，请在服务器启动时检查日志中是否有类似下面这样的行：

Workday client configured: token_url=... api_base=... client_id=...

并确认该 URL 与 Workday 的 API Client 页面显示的、你的客户端对应的令牌端点完全一致。

如果你缺少四个必需变量中的任意一个，服务器会在启动时记录一条明确的错误并退出，而不会在第一次工具调用时令人困惑地失败。

如果你的集成还需要写访问权限，则需要在 API 客户端上配置额外的作用域/授权——此服务器只会发出 GET 请求，因此此处实现的功能不需要任何写作用域。

本地运行

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

export WORKDAY_TENANT=acme_gms
export WORKDAY_HOST=https://wd2-impl-services1.workday.com
export WORKDAY_CLIENT_ID=your-client-id
export WORKDAY_CLIENT_SECRET=your-client-secret

python server.py

服务器监听 http://0.0.0.0:8080/mcp/（Streamable HTTP）。将任何兼容 MCP 的客户端（Claude、MCP Inspector 等）指向该 URL。

使用 MCP Inspector 快速检查：

npx @modelcontextprotocol/inspector http://localhost:8080/mcp/

部署到 Google Cloud Run

1. 构建并推送镜像（使用 Cloud Build，因此你无需在本地安装 Docker）：

   gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/workday-mcp

   或者本地构建并推送：

   docker build -t gcr.io/YOUR_PROJECT_ID/workday-mcp .
   docker push gcr.io/YOUR_PROJECT_ID/workday-mcp

2. 将客户端密钥存储在 Secret Manager 中（在生产环境中不要以明文环境变量的形式传递）：

   echo -n "your-client-secret" | gcloud secrets create workday-client-secret --data-file=-

3. 部署：

   gcloud run deploy workday-mcp \
     --image gcr.io/YOUR_PROJECT_ID/workday-mcp \
     --region YOUR_REGION \
     --set-env-vars WORKDAY_TENANT=acme_gms,WORKDAY_HOST=https://wd2-impl-services1.workday.com,WORKDAY_CLIENT_ID=your-client-id \
     --set-secrets WORKDAY_CLIENT_SECRET=workday-client-secret:latest \
     --no-allow-unauthenticated

   --no-allow-unauthenticated 是有意为之：此服务器按设计不实现自身的认证层，因此访问控制预期来自 Cloud Run IAM（roles/run.invoker）或位于其前面的反向代理。仅将 run.invoker 授予那些应该能够调用它的身份/服务，例如：

   gcloud run services add-iam-policy-binding workday-mcp \
     --region YOUR_REGION \
     --member="serviceAccount:your-caller@your-project.iam.gserviceaccount.com" \
     --role="roles/run.invoker"

4. Cloud Run 会自动设置 PORT，而应用已经在 0.0.0.0:$PORT 上监听，因此无需进一步配置。容器完全无状态（不写入任何本地文件），因此可以干净地缩容到零并重新扩容，并且多个实例/副本可以并发运行，无需担心任何共享状态。

错误处理与分页行为

• Workday 返回的 4xx/5xx 响应会被转换为简短、可读的错误消息，并作为 MCP 工具错误（isError: true）返回——绝不会是原始堆栈跟踪。

• 网络故障（DNS、超时、连接被拒绝）同样会被捕获并以相同方式返回。

• 列表端点返回单页数据（limit，默认 20，最大 100；offset，默认 0）。如果还有更多结果，响应会告诉你总数以及下一步应传入的 offset，而不是自动获取每一页。