使用说明

项目简介

本项目 'mcp-server-harvest-time-tracking' 是一个基于 Model Context Protocol (MCP) 的服务器实现，它将 Harvest（一款流行的在线时间追踪和项目管理软件）的 REST API 封装成 MCP 协议的工具 (Tools)，使得支持 MCP 协议的 LLM 客户端能够方便地与 Harvest 服务进行交互，实现时间记录、项目管理、客户信息查询和生成报告等功能。

主要功能点

时间条目管理: 支持查看、创建、更新、删除、停止、重启时间条目等完整的时间追踪功能。
客户信息管理: 支持客户列表查询、客户信息获取、创建、更新和删除客户信息。
项目信息管理: 支持项目列表查询、项目信息获取、创建、更新和删除项目信息。
报表生成: 支持生成客户、项目、任务和团队的时间报告，方便进行工时分析和项目监控。
标准化接口: 通过 MCP 协议以标准化的 JSON-RPC 接口对外提供服务，易于集成到各种支持 MCP 协议的 LLM 客户端。

安装步骤

克隆仓库:

git clone https://github.com/CodifyAG/mcp-server-harvest-time-tracking.git
cd mcp-server-harvest-time-tracking

配置环境变量: 复制 '.env.example' 文件为 '.env'，并根据你的 Harvest 账户信息修改 '.env' 文件中的 'HARVEST_ACCOUNT_ID' 和 'HARVEST_ACCESS_TOKEN'。
```
cp .env.example .env
# 编辑 .env 文件，填入你的 Harvest Account ID 和 Access Token
```
你需要拥有 Harvest 账户并获取 Access Token，Access Token 通常在 Harvest 的 OAuth 应用设置中创建。
设置虚拟环境并安装依赖:
```
make setup
```
这个命令会创建 Python 虚拟环境并安装项目所需的依赖包，包括 'mcp' (MCP协议库), 'requests' (HTTP请求库) 和 'python-dotenv' (环境变量加载库)。

服务器配置

为了让 MCP 客户端（例如 Claude Desktop）连接到此 MCP 服务器，你需要配置客户端的 'claude_desktop_config.json' 文件。在 'mcpServers' 字段中添加如下配置：

{
  "mcpServers": {
    "harvest-time-tracking": {  //  服务器名称，客户端用此名称引用
      "command": "python",      //  启动服务器的命令
      "args": ["-m", "src.server"], // 启动服务器命令的参数，这里指定运行 src 目录下的 server.py 模块
      "cwd": "/path/to/mcp-server-harvest-time-tracking", //  服务器代码仓库的根目录，请替换为实际路径
      "env": {                  //  服务器运行时需要的环境变量
        "HARVEST_ACCOUNT_ID": "your-harvest-account-id", //  你的 Harvest Account ID，请替换为实际值
        "HARVEST_ACCESS_TOKEN": "your-harvest-access-token" // 你的 Harvest Access Token，请替换为实际值
      }
    }
  }
}

请将 '/path/to/mcp-server-harvest-time-tracking' 替换为你克隆仓库的实际本地路径，并将 'your-harvest-account-id' 和 'your-harvest-access-token' 替换为你在 Harvest 获取的账户 ID 和 Access Token。

基本使用方法

配置完成后，启动 MCP 客户端（如 Claude Desktop），客户端将自动连接到此 MCP 服务器。你可以通过自然语言指令，指示 LLM 客户端调用 Harvest 的功能。例如，你可以让 Claude 调用 'list_time_entries' 工具来查询今天的工时记录，或者调用 'create_time_entry_duration' 工具来快速记录新的工作时间。

示例 (通过 Claude Desktop 指令):

"列出我今天在所有项目上的时间记录" (客户端可能会调用 'list_time_entries' 工具，并根据上下文自动填充日期参数)
"帮我记录在 '项目A' 上工作了 2 小时，任务是 '文档编写'" (客户端可能会调用 'create_time_entry_duration' 工具，并需要你提供项目和任务的 ID，或者通过进一步对话来 уточнить)
"查询客户 'ABC 公司' 的信息" (客户端可能会调用 'get_client' 工具，需要提供客户 ID 或名称进行查询)
"生成上个月的项目时间报告" (客户端可能会调用 'get_projects_time_report' 工具，并根据上下文或用户输入确定日期范围)

具体的使用方式取决于 MCP 客户端的功能和设计，你需要参考你使用的 MCP 客户端的文档来了解如何通过自然语言指令调用 MCP 服务器提供的工具。

关键词