Zoho Projects MCP

开源的 Zoho Projects 本地 MCP，同时提供 Codex 插件和 DeepSeek Harness（DSH）插件。支持筛选任务与问题、创建工单、分配人员、更新详情和进度、评论、附件及受控状态流转。

普通用户请直接阅读：macOS / Windows / Linux 安装与授权说明书。 说明书包含 Self Client 创建、权限复制、授权码填写、初始化、检查和常见问题，无需修改源码。

所有写入都必须先生成预览，再由用户明确确认。项目不包含任何公司门户 ID、个人 ZPUID、OAuth 凭据或内部项目状态 ID。

功能

• 按项目、负责人、标题、状态和截止日期筛选任务或问题。

• 按工单前缀查找任务，读取详情、评论和附件元数据。

• 创建任务、子任务或问题，分配负责人，更新支持的字段。

• 一次回填字段、评论、本地附件和状态，并保留执行回执。

• 重复确认返回原回执；不确定的写入不会自动重试。

• 不提供删除、关闭、批量修改或任意 Zoho API 请求工具。

DSH 中的工具名为 mcp__zoho-projects__<工具名>；Codex 使用同一个 MCP 服务。

Related MCP server: mcp-jira-scoped

环境要求

• macOS、Windows 或带 Secret Service 的 Linux 桌面。

• uv，用于准备 Python 3.12 和依赖。

• Zoho Projects 账号及目标项目权限。

• Codex CLI，或包含 @deepseek-ai/dsh-mcp-client 的 DSH profile。

OAuth 凭据保存到当前操作系统用户的凭据存储：macOS 钥匙串、Windows 凭据管理器，或 Linux 的 GNOME Keyring、KWallet 等 Secret Service。无桌面 Secret Service 的 Linux 环境需要额外配置。

快速开始

1. 安装命令

从公开 Git 仓库安装，无需手工克隆：

uv tool install git+https://github.com/amosbake/zoho-projects-mcp.git

开发本地检出时使用：

uv tool install .

2. 在 Zoho 获取授权信息

在 Zoho API Console 中创建 Self Client，然后按说明书生成包含任务、问题、成员和可选附件权限的一次性授权码。完整步骤和权限文本见普通用户说明书。

3. 初始化

macOS / Linux 示例：

zoho-projects setup \
  --portal-id '你的数字门户ID' \
  --user-id '你的数字ZPUID' \
  --region cn \
  --attachment-root "$HOME/Documents"

Windows PowerShell 示例：

zoho-projects setup `
  --portal-id '你的数字门户ID' `
  --user-id '你的数字ZPUID' `
  --region cn `
  --attachment-root "$HOME\Documents"

国际区使用 --region global。命令依次要求输入 Client ID、Client Secret 和一次性授权码，自动换取 Refresh Token 并保存到系统凭据存储。敏感输入不会显示在屏幕上。

已有完整 OAuth JSON 的高级用户可使用 --oauth-json；凭据已由其他安全配置流程写入系统凭据存储时，使用 --skip-oauth，并用 --keychain-account、--keychain-service 指定条目。

检查非敏感配置并执行真实只读连接：

zoho-projects config
zoho-projects doctor --online

配置文件默认位置：

Access Token 缓存、写入状态和回执也保存在用户目录，不写入插件源码。不要把 OAuth 信息、Token 缓存或用户配置提交到 Git。

安装 Codex 插件

codex plugin marketplace add amosbake/zoho-projects-mcp
codex plugin add zoho-projects@zoho-projects-community

插件通过跨平台的 uv run 启动本地 MCP，个人配置从统一用户目录读取。首次启动可能需要下载依赖。

也可以直接把 zoho-projects-mcp 注册到其他支持 stdio 的客户端。插件方式和直接注册方式不要同时启用同名服务。

安装 DSH 插件

dsh plugin --profile web add github:amosbake/zoho-projects-mcp
dsh --profile web --dump-config

package.json 声明 DSH bundle，cordis.patch.yml 使用官方 @deepseek-ai/dsh-mcp-client。默认从用户目录下的 .local/bin 启动命令；位置不同时，在 profile 自己的 patch 中覆盖 zoho-projects-mcp 行的 command。

使用示例

• “查询我负责的未完成任务，按截止日期排序。”

• “查找 TASK-123，读取完整详情和最近评论。”

• “在指定任务下创建子任务，先给我预览。”

• “把这份本地文档上传到指定任务，并补充进度评论。”

写入流程：

1. Agent 调用 zoho_preview_*。

2. Agent 展示目标、字段变化和附件。

3. 用户对该预览明确同意。

4. Agent 调用 zoho_confirm_write 并返回回执。

写入超时、5xx 或结果无法核对时，应先只读核对，不要自动重试。

状态流转配置

状态名称和数字 ID 因 Zoho 门户及项目而异。仓库只提供 examples/ 示例，不包含真实项目映射。未配置白名单时，不允许状态流转。

可在 setup 中导入管理员提供的文件：

zoho-projects setup --skip-oauth \
  --status-map /path/to/status-map.json \
  --status-whitelist /path/to/status-whitelist.json

状态映射格式为 projects -> 项目ID -> tasks/issues -> 状态名称 -> 数字状态ID。白名单格式为 tasks/issues -> 当前状态 -> 可流转目标列表。

附件安全

只有 --attachment-root 明确允许的目录可以用于上传；默认没有允许目录。多个目录可重复传入该参数。附件必须是普通文件、不能是符号链接，单文件上限为 20 MB。

CLI

zoho-projects find '{"prefix":"TASK-123"}'
zoho-projects search '{"kind":"both","owner_id":"YOUR_ZPUID","limit":10}'
zoho-projects preview-create-task '{"project_id":"...","name":"测试子任务"}'
zoho-projects confirm '{"confirmationId":"..."}'

开发与发布

uv venv --python 3.12
uv pip install --python .venv/bin/python -e .
uv build
npm pack --dry-run

发布时同步更新 .codex-plugin/plugin.json、pyproject.toml、src/zoho_projects_mcp/__init__.py 和 package.json 的版本。Python 包可发布到 PyPI，DSH bundle 可发布到 npm 或直接从 GitHub 安装，Codex 插件通过 Git 仓库中的 Marketplace 清单安装。

本项目是社区实现，不隶属于 Zoho、OpenAI 或 DeepSeek。使用 Zoho API 时仍需遵守对应服务条款和用户权限。

License

MIT