AI导哈

Harvest时间跟踪集成服务

Harvest MCP Server是一个与Harvest时间跟踪API集成的模型上下文协议服务器，允许AI助手如Claude与您的Harvest账户交互，检查项目、任务和记录时间条目。

  • by baspenny
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 baspenny/harvest-mcp

使用说明

收获MCP服务器

一个模型上下文协议（MCP）服务器，与 收获 时间追踪API。该服务器允许像Claude这样的人工智能助手与您的Harvest帐户进行交互，以检查项目、任务和记录时间条目。

特性

  • 验证凭据 并检索经过身份验证的用户信息
  • 列出活动项目 及其相关任务
  • 检索时间条目 适用于任何日期或日期范围，可选择项目/用户筛选
  • 记录时间条目 针对特定项目和任务
  • 启动/停止/重启定时器 实时跟踪时间
  • 删除时间条目 在需要时
  • 灵活的身份验证：支持环境变量和每次呼叫凭据

先决条件

  • Node.js（建议使用v16或更高版本）
  • 具有API访问权限的Harvest帐户
  • 收获个人访问令牌和帐户ID

获取Harvest证书

  1. 登录您的Harvest帐户
  2. 首选 设置 → 开发者
  3. 创建新 个人访问令牌
  4. 注意你的 账户ID （在URL或令牌创建页面中可见）

安装

  1. 克隆此存储库：
git clone <repository-url>
cd harvest-mcp
  1. 安装依赖项：
npm install
  1. 构建TypeScript代码：
npm run build

配置

选项1：环境变量（建议用于MCP）

在MCP客户端中配置服务器（例如，Claude Desktop）：

克劳德桌面 (~/.claude.json 或 %APPDATA%/Claude/config.json 在Windows上）：

{
  "mcpServers": {
    "harvest": {
      "command": "node",
      "args": ["/absolute/path/to/harvest-mcp/build/index.js"],
      "env": {
        "HARVEST_ACCESS_TOKEN": "your-token-here",
        "HARVEST_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

重要:

  • 使用绝对路径 build/index.js
  • 修改配置后重新启动Claude Desktop
  • 重建项目(npm run build)任何代码更改后

选项2：每次通话凭据（无状态模式）

如果您不想使用环境变量，可以在每次工具调用时传递凭据：

{
  "access_token": "your-token-here",
  "account_id": "your-account-id"
}

可用工具

get_my_profile

验证凭据并检索有关已验证身份的用户的信息。

参数：

  • access_token （可选）：收获个人访问令牌
  • account_id （可选）：收获账户ID

示例响应：

Authenticated as: John Doe

get_time_entries

检索特定日期或日期范围的时间条目。支持按项目和用户进行筛选。

参数：

  • access_token （可选）：收获个人访问令牌
  • account_id （可选）：收获账户ID
  • from （可选）：YYYY-MM-DD格式的开始日期（默认为今天）
  • to （可选）：YYYY-MM-DD格式的结束日期（默认为 from 日期）
  • project_id （可选）：筛选特定项目的条目
  • user_id （可选）：筛选特定用户的条目（默认为当前用户）

示例用法：

获取今天的条目：

{}

获取特定日期的条目：

{
  "from": "2026-02-01"
}

获取日期范围的条目：

{
  "from": "2026-02-01",
  "to": "2026-02-05"
}

获取本周特定项目的条目：

{
  "from": "2026-02-03",
  "to": "2026-02-07",
  "project_id": 67890
}

示例响应：

Found 3 time entries for 2026-02-04:

Total hours: 6.50

[
  {
    "id": 123456789,
    "spent_date": "2026-02-04",
    "hours": 2.5,
    "notes": "Implemented user authentication",
    "project": {
      "id": 67890,
      "name": "My Project"
    },
    "task": {
      "id": 222,
      "name": "Development"
    }
  },
  ...
]

list_active_projects

列出分配给经过身份验证的用户的所有活动项目，包括其关联的任务。默认情况下，返回简洁、可读的格式，以尽量减少上下文使用。

参数：

  • access_token （可选）：收获个人访问令牌
  • account_id （可选）：收获账户ID
  • format （可选）：输出格式- 'compact' （默认）用于简洁视图或 'full' 完整的JSON

示例响应（压缩格式-默认）：

Client: Acme Corp
  → Website Redesign (project_id: 14308070)
     Tasks: Design (8083367), Development (8083368), Testing (8083369)

Client: 123 Industries
  → Online Store - Phase 1 (project_id: 14308069)
     Tasks: Graphic Design (8083365), Programming (8083366)

示例响应（完整格式）：

[
  {
    "id": 12345,
    "project": {
      "id": 67890,
      "name": "My Project",
      "code": "PROJ"
    },
    "task_assignments": [
      {
        "id": 111,
        "task": {
          "id": 222,
          "name": "Development"
        }
      }
    ],
    "is_project_manager": false,
    "budget": null,
    ...
  }
]

log_time

为特定项目和任务创建时间条目。

参数：

  • access_token （可选）：收获个人访问令牌
  • account_id （可选）：收获账户ID
  • project_id （必填）：项目ID
  • task_id （必填）：任务ID
  • hours （必填）：要记录的小时数
  • spent_date （可选）：YYYY-MM-DD格式的日期（默认为今天）
  • notes （可选）：所执行工作的描述

示例用法：

{
  "project_id": 67890,
  "task_id": 222,
  "hours": 2.5,
  "spent_date": "2026-02-04",
  "notes": "Implemented user authentication"
}

示例响应：

Success! Time entry created with ID: 123456789

start_timer

为特定项目和任务启动运行计时器。计时器将跟踪时间直到停止。

参数：

  • access_token （可选）：收获个人访问令牌
  • account_id （可选）：收获账户ID
  • project_id （必填）：项目ID
  • task_id （必填）：任务ID
  • spent_date （可选）：YYYY-MM-DD格式的日期或相对日期（默认为今天）
  • notes （可选）：正在执行的工作的描述

示例用法：

{
  "project_id": 67890,
  "task_id": 222,
  "notes": "Working on user authentication"
}

示例响应：

Success! Timer started with ID: 123456789

stop_timer

停止运行计时器。这使用了Harvest的专用 /stop endpoint用于根据经过的时间计算小时数。

参数：

  • access_token （可选）：收获个人访问令牌
  • account_id （可选）：收获账户ID
  • time_entry_id （必填）：要停止的运行计时器的ID

示例用法：

{
  "time_entry_id": 123456789
}

示例响应：

Success! Timer stopped.

Project: My Project
Task: Development
Total time logged: 2.5 hours
Date: 2026-02-12

restart_timer

重新启动之前停止的计时器。这使用了Harvest的专用 /restart 端点以恢复跟踪。

参数：

  • access_token （可选）：收获个人访问令牌
  • account_id （可选）：收获账户ID
  • time_entry_id （必填）：要重新启动的已停止计时器的ID

示例用法：

{
  "time_entry_id": 123456789
}

示例响应：

Success! Timer restarted.

ID: 123456789
Project: My Project
Task: Development
Date: 2026-02-12

get_running_timer

检查当前是否有计时器在运行，并查看经过的时间。

参数：

  • access_token （可选）：收获个人访问令牌
  • account_id （可选）：收获账户ID

示例响应：

Timer is running:

ID: 123456789
Project: My Project
Task: Development
Notes: Working on user authentication
Elapsed: 1h 23m

[detailed JSON data]

delete_time_entry

删除特定时间条目。

参数：

  • access_token （可选）：收获个人访问令牌
  • account_id （可选）：收获账户ID
  • time_entry_id （必填）：要删除的时间条目的ID

示例用法：

{
  "time_entry_id": 123456789
}

示例响应：

Success! Time entry 123456789 has been deleted.

发展

构建项目

npm run build

在开发模式下运行（带ts节点）

npm run dev

仅进行类型检查

npx tsc --noEmit

项目结构

harvest-mcp/
├── index.ts          # Main server implementation
├── build/            # Compiled JavaScript output
│   └── index.js      # Entry point for MCP clients
├── package.json      # Dependencies and scripts
├── tsconfig.json     # TypeScript configuration
└── README.md         # This file

使用Claude Desktop

配置后，您可以使用自然语言与Harvest交互：

交互示例：

  • “我在Harvest中分配了哪些项目？”
  • “显示我今天的时间条目”
  • “我今天记录了多少小时？”
  • “显示我上周一的时间条目”（2026-02-03）
  • “获取2月1日至2月5日的所有参赛作品”
  • “显示本周67890项目的时间条目”
  • 在项目12345、任务222中记录3小时，并注明“已修复身份验证错误”
  • 为项目67890、任务222启动计时器
  • “计时器在运行吗？”
  • “停止我当前的计时器”
  • “重新启动计时器123456789”
  • “删除时间条目123456789”
  • “显示我的Harvest个人资料”

故障排除

服务器未连接

  • 确保构建步骤成功完成(npm run build)
  • 验证MCP配置中指向的绝对路径 build/index.js
  • 配置更改后重新启动MCP客户端

身份验证错误

  • 仔细检查您的个人访问令牌和帐户ID
  • 确保在环境变量中正确设置凭据或通过工具调用传递凭据
  • 验证您的Harvest帐户是否已启用API访问

缺少项目或任务

  • 确保你被分配到Harvest的项目中
  • 仅返回活动项目 list_active_projects
  • 检查您的用户是否具有必要的权限

API 参考

此服务器使用 嘉实API v2.关键端点：

  • GET /users/me -当前用户信息
  • GET /users/me/project_assignments -用户的项目分配
  • GET /time_entries -检索时间条目
  • POST /time_entries -创建时间条目或启动计时器
  • PATCH /time_entries/{id}/stop -停止正在运行的计时器
  • PATCH /time_entries/{id}/restart -重新启动已停止的计时器
  • DELETE /time_entries/{id} -删除时间条目

许可证

国际学生委员会

作者

Sebastian Pfennigwerth

贡献

欢迎投稿！请随时提交问题或拉取请求。

相关 MCP