AI导哈

时间追踪与项目管理服务器

Harvest MCP服务器是一个集成Harvest时间追踪和项目管理API的工具，帮助用户管理时间记录、项目、客户等。

  • by taiste
  • Python
  • 本地部署
  • 39 星标
  • 更新于
在 GitHub 查看 taiste/harvest-mcp-server

使用说明

收获MCP服务器

此MCP（模型上下文协议）服务器提供与收获时间跟踪和项目管理API的集成。它允许Claude和其他兼容MCP的AI助手与您的Harvest帐户进行交互，帮助您管理时间条目、项目、客户等。

特性

服务器提供以下功能：

用户

  • 列出用户
  • 获取用户详细信息

时间条目

  • 列出具有筛选选项的时间条目
  • 创建新的时间条目
  • 启动/停止计时器
  • 查询时间输入详细信息
  • 获取未提交的时间表（尚未提交审批的时间条目）

项目

  • 列出具有筛选选项的项目（按客户端、is_active、updated_since、page、per_page）
  • 检索详细的项目信息
  • 创建新项目
  • 更新现有项目（也用于存档：pass is_active=False)
  • 删除项目（破坏性-也删除项目的时间条目和费用，但保留发票；建议存档）

任务分配

  • 列出任务分配（全账户或项目范围）
  • 检索详细的任务分配信息
  • 创建新的任务分配（将任务链接到项目）
  • 更新现有任务分配
  • 删除任务分配（仅当没有记录时间条目时）

用户分配

  • 列出用户分配（帐户范围或项目范围）
  • 检索详细的用户分配信息
  • 创建新的用户分配（将用户链接到项目）
  • 更新现有用户分配
  • 删除用户分配（仅当没有记录时间条目或费用时）

客户

  • 列出具有筛选选项的客户端
  • 检索详细的客户信息

任务

  • 列出具有筛选选项的可用任务

估计

  • 列出带有过滤选项的估计值（按客户端、状态、日期范围、updated_since）
  • 检索详细的估算信息
  • 按面向用户的数字查找估计值（例如“79”）
  • 列出与估算相关的消息
  • 使用行项目创建新的估算
  • 更新现有估算（通过添加/更新/删除行项目 _destroy)
  • 在不发送电子邮件的情况下更改估计状态（发送、接受、拒绝、重新打开）
  • 发送估价信息（将估价通过电子邮件发送给收件人）
  • 删除估计数

安装说明

先决条件

  • Python 3.10或更高版本
  • 具有API访问权限的Harvest帐户
  • Harvest API密钥和帐户ID

与Claude Desktop集成

  1. 创建或编辑您的Claude Desktop配置文件：

    • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows（MSIX安装--默认从 claude.ai/下载): %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json
    • Windows（较旧/非MSIX安装）： %APPDATA%\Claude\claude_desktop_config.json

  2. 添加Harvest MCP服务器配置：

     {
     "mcpServers": {
         "harvest": {
             "command": "uv",
             "args": [
               "run",
               "--directory",
               "change_directory",
               "harvest-mcp-server.py"
             ],
             "env": {
                 "HARVEST_ACCOUNT_ID": "account_id",
                 "HARVEST_API_KEY": "api_key"
             }
         }
     }
 }

  3. 重新启动克劳德桌面。

  4. 通过在Claude的界面中查找锤子图标来验证集成。

查询示例

连接后，您可以通过以下查询向Claude询问您的Harvest数据：

  • “显示我上周的时间条目”
  • “列出我的所有活动项目”
  • “为项目[project_id]和任务[task_id]启动计时器”
  • “显示所有活动客户”
  • “列出所有可用任务”
  • “获取本月未提交的时间表”
  • “显示用户[user_id]的未提交时间条目”
  • “显示本季度所有已接受的估计值”
  • “查找编号为[数字]的估算值”
  • “使用这些行项目为客户端[client_id]创建估算草案…”
  • “将估计[id]标记为已发送”
  • “电子邮件估计[id]client@example.com"
  • 为客户端[client_id]创建一个名为[name]的新项目，按项目计费，无预算
  • “存档项目[project_id]”
  • “将任务[task_id]分配给可计费的项目[project_id]”
  • “将用户[user_id]设置为项目[project_id]的项目经理”
  • “列出分配给项目[project_id]的每个人”

定制

您可以修改服务器代码以添加更多功能，或自定义现有工具以更好地适应您的工作流程。服务器使用FastMCP，只需使用 @mcp.tool() 装饰师。

故障排除

  • API错误：请确保您的Harvest API密钥和帐户ID正确，并具有必要的权限。
  • 连接问题：验证您的Claude Desktop配置是否具有指向服务器脚本的正确路径。
  • 缺少的依赖：确保您已在Python环境中安装了所有必需的包。

只读模式

您可以通过设置以只读模式运行服务器 HARVEST_READ_ONLY 环境变量 true这将禁用所有写入操作（创建时间条目、启动/停止计时器、创建/更新/删除估计、更改估计状态、发送估计消息以及创建/更新或删除项目、任务分配和用户分配），同时保持所有读取操作可用。

{
    "mcpServers": {
        "harvest": {
            "command": "uv",
            "args": [
              "run",
              "--directory",
              "change_directory",
              "harvest-mcp-server.py"
            ],
            "env": {
                "HARVEST_ACCOUNT_ID": "account_id",
                "HARVEST_API_KEY": "api_key",
                "HARVEST_READ_ONLY": "true"
            }
        }
    }
}

启用只读模式时，任何调用写工具的尝试都将返回一条错误消息，说明服务器处于只读模式以及如何启用写访问。

安全说明

此服务器需要您的Harvest API凭据才能运行。确保：

  • 确保API密钥的安全
  • 不要共享claude_desktop_config.json文件
  • 请考虑为此集成使用权限有限的专用API密钥

相关 MCP