Deputy MCP

Deputy MCP

询问 Claude “我下次什么时候上班？”，即可从你的 Deputy 排班表中获取答案。

Deputy MCP 是一个本地 MCP 服务，可让 AI Agent 读取你的班次、工时表和团队排班；只有在你启用后，才能对其执行操作。 它在你的设备上运行，连接到 Deputy，并支持普通员工账号。

你可以询问什么

• “我下次什么时候上班？”
• “我上周工作了多少小时？”
• “现在谁在上班？” （需要经理权限）
• “帮我打卡上班。” （已启用写入功能）
• “接下周六的空缺班次。” （已启用写入功能；会先请你确认）

安装

需要 uv 和 Python 3.11 或更高版本。请先选择访问 方式：

模式	适用对象	从这里开始
OAuth	任何员工	员工登录
API token	Deputy 管理员	管理员设置
日历订阅源	无 API 访问权限	使用 客户端设置设置 DEPUTY_CALENDAR_URL；仅限查看你自己的排班表

Employee OAuth

在 https://once.deputy.com/my/oauth_clients 创建个人应用，并将重定向 URI 设置为 http://localhost:8823/callback。请在此处创建，而不要在你的安装实例中的 Settings → Developer 下创建：在安装实例内创建的应用会导致登录失败，并提示 invalid_client。在 Bash 中替换占位符，登录，然后向 Claude Code 注册该服务：

export DEPUTY_OAUTH_CLIENT_ID='your-client-id'
export DEPUTY_OAUTH_CLIENT_SECRET='your-client-secret'
uvx deputy-mcp login
claude mcp add deputy \
  -e DEPUTY_OAUTH_CLIENT_ID="$DEPUTY_OAUTH_CLIENT_ID" \
  -e DEPUTY_OAUTH_CLIENT_SECRET="$DEPUTY_OAUTH_CLIENT_SECRET" \
  -- uvx deputy-mcp

登录会打开浏览器，并默认将 OAuth 令牌存储在你的操作系统钥匙串中。 请使用同一操作系统用户运行登录流程和 Claude Code。没有终端（例如使用 Claude Desktop bundle）？设置这两个 OAuth 值，并让助手帮你登录：deputy_login 工具会打开相同的浏览器登录页面。

Admin API token

准备好 Deputy API 令牌和安装 URL 后，直接注册即可；无需 OAuth 登录：

claude mcp add deputy \
  -e DEPUTY_API_TOKEN=your-deputy-token \
  -e DEPUTY_BASE_URL=https://your-company.eu.deputy.com \
  -- uvx deputy-mcp

Codex CLI

如需访问你自己的排班表，请将 ... 替换为你的私人日历订阅源 URL：

codex mcp add deputy --env DEPUTY_CALENDAR_URL=... -- uvx deputy-mcp

首次运行 uvx 时会下载依赖项；如果 Codex 报告工具不可用，请在 ~/.codex/config.toml 的 [mcp_servers.deputy] 下设置 startup_timeout_sec = 60。

Claude Desktop 用户：从 Releases 页面 下载 .mcpb bundle，并将其拖到 Settings → Extensions 中（在 Windows 上双击可能无法打开）。在 Configure 下填写一种访问模式，然后让 Claude 帮你登录。 其他 MCP 客户端和 Docker：参见其他安装方式。 所有设置都列在 .env.example 中。

工具

• 你的数据（任何账号）：deputy_whoami、deputy_get_my_roster、 deputy_next_shift、deputy_get_my_timesheets、deputy_get_my_colleagues、 deputy_get_my_calendar_url、deputy_get_areas
• 团队（需要经理权限）：deputy_get_team_roster、deputy_who_is_working、 deputy_get_employee_info、deputy_search_shifts
• 操作（仅在 DEPUTY_ALLOW_WRITES=true 时可用）：deputy_clock_in、 deputy_clock_out、deputy_set_unavailability、 deputy_claim_open_shift

默认安全

• 只读，除非设置 DEPUTY_ALLOW_WRITES=true；在此之前，Agent 无法使用操作工具。
• 认领班次前需要你确认，因为这会跳过 Deputy 的审批步骤。
• 不猜测：如果名称匹配多个人，你会看到名单，而不是第一个匹配的人。
• 凭证保护：默认情况下，令牌只会发送到 https://*.deputy.com，OAuth 令牌保存在操作系统的钥匙串中；错误信息会在展示给 Agent 前清除机密信息。

状态

日常读取工具和 OAuth 登录已使用员工账户在真实的 Deputy 安装环境中测试。经理工具、操作以及 OAuth 令牌刷新已通过自动化测试覆盖，但尚未在真实安装环境中验证。与 Deputy 没有关联。

更多信息

• 构建方式及原因
• 贡献指南 · 安全 · 更新日志 · 路线图

许可证

MIT