Harvest Time Tracking MCP Server

Harvest 时间跟踪 MCP 服务

这是一个基于 TypeScript 的 Harvest 时间跟踪应用 MCP（Model Context Protocol）服务，可让大模型客户端与 Harvest 账户交互。

安装

npx -y @mayankg0324/mcp-server-harvest

前提条件

• Node.js >= 18（或用于开发的 Bun Runtime）
• 可访问 API 的 Harvest 账户
• Harvest API 个人访问令牌
• Harvest 账户 ID

有关如何创建个人访问令牌的更多详情，请参阅 Harvest API 文档。

可用工具

工具	描述	输入	输出
get-company	获取公司信息	无	公司信息（名称、URL、ID 和货币）
search-clients	搜索客户	• name：string（可选）- 客户名称 • isActive：boolean（可选）- 活跃状态	客户列表，包含 ID 和详情
get-client	获取客户信息	• clientId：string - 客户 ID	客户详细信息
search-projects	搜索项目	• name：string（可选）- 项目名称 • clientId：string（可选）- 客户 ID • isActive：boolean（可选）- 活跃状态	项目列表，包含 ID 和详情
get-project	获取项目信息	• projectId：string - 项目 ID	项目详细信息
list-users	列出所有用户	无	用户列表，包含 ID 和详情
get-user	获取用户信息	• userId：string - 用户 ID	用户详细信息
list-project-users	列出项目用户分配情况	• projectId：string - 项目 ID	分配到项目的用户列表
list-project-tasks	列出项目任务分配情况	• projectId：string - 项目 ID	分配到项目的任务列表
search-time-entries	搜索时间条目	• from：string（可选）- 开始日期（YYYY-MM-DD） • to：string（可选）- 结束日期（YYYY-MM-DD） • userId：string（可选）- 用户 ID • projectId：string（可选）- 项目 ID • clientId：string（可选）- 客户 ID	时间条目列表，包含详情
get-time-entry	获取时间条目详情	• timeEntryId：string - 时间条目 ID	时间条目详细信息
create-time-entry	创建新的时间条目	• projectId：string - 项目 ID • taskId：string - 任务 ID • userId：string - 用户 ID • hours：number - 耗时小时数 • notes：string（可选）- 其他备注	已创建时间条目的详情

注意： 更多工具即将推出。

使用方法

Claude Desktop

打开 Claude 桌面配置文件 claude-desktop-config.json，并在 mcpServers 下添加以下内容：

{
  "mcpServers": {
    "Harvest": {
      "command": "npx",
      "args": [
        "-y",
        "@mayankg0324/mcp-server-harvest"
      ],
      "env": {
        "HARVEST_ACCOUNT_ID": "<Harvest Account ID>",
        "HARVEST_ACCESS_TOKEN": "<Harvest Personal Access Token>",
        "HARVEST_BASE_URL": "<Harvest Base URL>"
      }
    }
  }
}

Cursor IDE

打开 Cursor IDE 配置文件 ~/.cursor/mcp.json 或 <project-root>/.cursor/mcp.json，并在 mcpServers 下添加以下内容：

{
  "mcpServers": {
    "Harvest": {
      "command": "npx",
      "args": [
        "-y",
        "@mayankg0324/mcp-server-harvest"
      ],
      "env": {
        "HARVEST_ACCOUNT_ID": "<Harvest Account ID>",
        "HARVEST_ACCESS_TOKEN": "<Harvest Personal Access Token>",
        "HARVEST_BASE_URL": "<Harvest Base URL>"
      }
    }
  }
}

故障排除

spawn npx ENOENT 或 env: node: No such file or directory

当 MCP 客户端（Claude Desktop、Cursor）在 PATH 中找不到 npx 或 node 时，就会发生这种情况。图形界面应用通常不会继承 shell 的 PATH，尤其是在使用 nvm、fnm 或 volta 等版本管理器时。

解决方法： 使用 npx 的完整路径，并在 PATH 环境变量中加入 Node 的 bin 目录：

# Find your npx and node paths
which npx
# e.g. /Users/you/.nvm/versions/node/v22.20.0/bin/npx

然后更新 MCP 配置：

{
  "mcpServers": {
    "Harvest": {
      "command": "/Users/you/.nvm/versions/node/v22.20.0/bin/npx",
      "args": [
        "-y",
        "@mayankg0324/mcp-server-harvest"
      ],
      "env": {
        "PATH": "/Users/you/.nvm/versions/node/v22.20.0/bin:/usr/bin:/bin",
        "HARVEST_ACCOUNT_ID": "<Harvest Account ID>",
        "HARVEST_ACCESS_TOKEN": "<Harvest Personal Access Token>",
        "HARVEST_BASE_URL": "<Harvest Base URL>"
      }
    }
  }
}

本地开发

1. 安装依赖：

   npm install
   

2. 构建项目：

   npm run build
   

   这将创建一个 dist 目录，其中包含编译后的 JavaScript 文件。

3. 若要使用本地开发版本，请修改 MCP 服务配置，使其指向本地构建目录：

   {
     "mcpServers": {
       "Harvest": {
         "command": "node",
         "args": [
           "path/to/local/build/dist/index.js"
         ],
         "env": {
           "HARVEST_ACCOUNT_ID": "<Harvest Account ID>",
           "HARVEST_ACCESS_TOKEN": "<Harvest Personal Access Token>",
           "HARVEST_BASE_URL": "<Harvest Base URL>"
         }
       }
     }
   }
   

4. 重启客户端应用（Claude、Cursor）以应用更改。

许可证

MIT