Harvest MCP (Dmarttinen)

收获MCP服务器

与Harvest时间跟踪集成的模型上下文协议（MCP）服务器。此服务器允许AI助手与您的Harvest帐户交互，以记录时间、查看项目、管理任务和跟踪您的工作时间。

当与Azure DevOps（ADO）MCP服务器和包含的示例技能结合使用时，您的AI助手可以自动查看ADO工作项的工时变化，并将相应的时间记录到Harvest中。

特性

• 列出活动项目及其详细信息
• 查看特定项目的任务
• 用笔记记录时间条目
• 查看今天的时间条目和总小时数
• 启动和停止计时器
• 更新现有时间条目
• Docker支持，易于部署

先决条件

• Node.js 20 或更高（用于当地发展）
• Docker和Docker Compose （用于集装箱化部署，可选）
• 收获账户 具有API访问权限
• Harvest个人访问令牌（PAT） — 在这里买一个
• Azure DevOps（ADO）MCP服务器 --如果要使用从ADO读取工作项的时间记录技能，则需要此项（请参阅 ADO MCP服务器 在......下面

快速入门--在游标中设置

1.获取您的收获证书

1. 首选https://id.getharvest.com/developers
2. 创建新的个人访问令牌
3. 注意你的 账户ID 和 访问令牌

2.设置环境变量

服务器希望您的Harvest凭据作为操作系统级环境变量可用。在系统中设置这些：

Windows（PowerShell--持久适用于您的用户）：

[System.Environment]::SetEnvironmentVariable("Harvest_ID", "your_account_id", "User")
[System.Environment]::SetEnvironmentVariable("Harvest_Token", "your_access_token", "User")

macOS/Linux（添加到 ~/.bashrc, ~/.zshrc或同等）：

export Harvest_ID="your_account_id"
export Harvest_Token="your_access_token"

设置后，重新启动终端（和游标），以便拾取新变量。

3.构建服务器

克隆此仓库并构建：

git clone 
cd HarvestMCP
npm install
npm run build

4.将MCP服务器添加到游标

在光标设置中，打开（或创建）MCP配置文件。在Windows上，这通常位于：

%USERPROFILE%\.cursor\mcp.json

添加Harvest服务器条目。样品见 examplemcp.json.md:

{
  "mcpServers": {
    "harvest": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:\\path\\to\\HarvestMCP\\build\\index.js"
      ],
      "env": {
        "HARVEST_ACCOUNT_ID": "${env:Harvest_ID}",
        "HARVEST_ACCESS_TOKEN": "${env:Harvest_Token}"
      }
    }
  }
}

重要提示： 更新中的路径 args 走向绝对的道路 build/index.js 在你的机器上。

这 ${env:...} 语法告诉Cursor在运行时读取操作系统环境变量中的值。这避免了将机密提交到配置文件中。

5.（可选）安装示例技能

Cursor代理技能示例见 example-skill.md此技能教AI助手如何查看ADO工作项的工时变化，并将相应的时间记录到Harvest中。

要使用它：

1. 复制 example-skill.md 到您的光标技能目录（例如。 ~/.cursor/skills/log-harvest-time/SKILL.md)
2. 如果需要，调整技能元数据（名称、描述）
3. 当您要求Cursor代理“记录时间”、“记录小时数”或“提交时间表”时，该技能将可供其使用

注： 此技能需要Harvest MCP服务器（此项目） 和 在Cursor中配置ADO MCP服务器。没有ADO MCP服务器，该技能无法读取工作项工时。

ADO MCP服务器

示例时间记录技能依赖于Azure DevOps MCP服务器来查询工作项并检测工时变化。您需要在Cursor MCP设置中与此Harvest服务器一起配置一个单独的ADO MCP服务器。

光标 mcp.json 应包含以下条目 两者 服务器，例如：

{
  "mcpServers": {
    "harvest": {
      // ... Harvest config as shown above ...
    },
    "ado": {
      // ... your ADO MCP server config ...
    }
  }
}

请参阅ADO MCP服务器的文档，了解其特定的设置说明和所需的环境变量（例如ADO PAT、组织URL等）。

包括示例

替代设置——VS代码

此回购还包括 .vscode/mcp.json 用于将服务器作为VS Code MCP服务器运行。同样的环境变量方法也适用——set Harvest_ID 和 Harvest_Token 作为操作系统环境变量，VS Code将在运行时通过 ${env:...} 语法。

安装选项

方案A：地方发展

安装依赖项并构建：

npm install
npm run build

直接运行服务器（在MCP客户端之外）：

npm start

如果你直接运行它，你必须提供 HARVEST_ACCOUNT_ID 和 HARVEST_ACCESS_TOKEN 在您的shell环境中。

选项B：Docker容器

使用Docker Compose构建和运行：

docker-compose up -d

Docker撰写阅读 HARVEST_ACCOUNT_ID / HARVEST_ACCESS_TOKEN 从您的shell环境中。它还将读到 .env 文件旁边 docker-compose.yml 如果你选择使用一个。

或者手动构建：

docker build -t harvest-mcp-server .
docker run -e HARVEST_ACCOUNT_ID=your_id -e HARVEST_ACCESS_TOKEN=your_token harvest-mcp-server

可用工具

服务器向MCP客户端公开以下工具：

list_projects

列出您Harvest帐户中的所有活动项目。

例子： “显示我的活动项目”

list_project_tasks

列出特定项目的所有任务。

参数：

• project_id （编号）：项目的ID

例子： “项目12345有哪些可用任务？”

log_time

在Harvest中记录一个时间条目。

参数：

• project_id （编号）：项目的ID
• task_id （number）：任务的ID
• hours （number）：要记录的小时数
• spent_date （字符串，可选）：YYYY-MM-DD格式的日期（默认为今天）
• notes （string，可选）：关于作品的注释

例子： “将2.5小时记录到项目12345，任务67890，并注明‘开发了新功能’”

get_todays_time

检索今天的所有时间条目和总小时数。

例子： “我今天记录了多少时间？”

start_timer

启动项目和任务的运行计时器。

参数：

• project_id （编号）：项目的ID
• task_id （number）：任务的ID
• notes （string，可选）：关于您正在处理的内容的注释

例子： 为项目12345、任务67890启动计时器

stop_timer

停止正在运行的计时器。

参数：

• time_entry_id （number）：要停止的时间条目的ID

例子： “停止计时器98765”

update_time_entry

更新现有的时间条目（小时、笔记、项目、任务或日期）。

参数：

• time_entry_id （number）：要更新的时间条目的ID
• hours （数字，可选）：新的小时数
• notes （字符串，可选）：更新注释
• project_id （数字，可选）：新项目ID
• task_id （数字，可选）：新任务ID
• spent_date （字符串，可选）：YYYY-MM-DD格式的新日期

例子： “将时间条目98765更新为3小时”

与Claude Desktop一起使用

要将此MCP服务器与Claude Desktop一起使用，请将其添加到配置文件中：

macOS/Linux： ~/Library/Application Support/Claude/claude_desktop_config.json

窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "harvest": {
      "command": "node",
      "args": ["/absolute/path/to/HarvestMCP/build/index.js"],
      "env": {
        "HARVEST_ACCOUNT_ID": "your_account_id",
        "HARVEST_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

发展

构建

npm run build

监视模式（更改后自动重建）

npm run watch

故障排除

“必须设置HARVEST_ACCOUNT_ID和HARVEST_ACCESS_TOKEN”

确保环境变量 Harvest_ID 和 Harvest_Token 在操作系统级别设置，并且在设置后您已重新启动Cursor/终端。MCP配置使用 ${env:Harvest_ID} 和 ${env:Harvest_Token} 在运行时注入这些。

“获取项目时出错：401”

您的访问令牌可能无效或已过期。从生成一个新的 Harvest开发者页面.

“获取项目时出错：403”

收获回报 403 Forbidden 当您的令牌没有端点权限时。此服务器使用 /v2/users/me/project_assignments 列出分配给您的项目和任务，这适用于普通成员帐户。如果你仍然得到403：

• 复查 HARVEST_ACCOUNT_ID 与您的令牌帐户匹配。
• 确认令牌未被撤销。
• 验证您是否被分配到Harvest中的至少一个项目。

Docker容器未启动

检查日志：

docker-compose logs harvest-mcp

确保 HARVEST_ACCOUNT_ID / HARVEST_ACCESS_TOKEN Docker Compose可以使用（在您的shell环境中或通过 .env 文件旁边 docker-compose.yml).

安全说明

• 永远不要将秘密（令牌、PAT）提交给git
• Harvest访问令牌提供对Harvest帐户的完全访问权限
• 考虑为不同的部署使用特定于环境的令牌
• 定期轮换您的访问令牌
• 这 ${env:...} MCP配置中的语法将秘密隐藏在配置文件之外

API费率限制

嘉实API有费率限制：

• 每个访问令牌每15秒100个请求
• 此服务器不包含内置速率限制

许可证

麻省理工学院

资源

• Harvest API文档
• Harvest开发者——个人访问令牌
• 模型上下文协议
• MCP TypeScript SDK