Harvest Natural Language Time Entry MCP Server

Harvest 自然言語タイムエントリー MCP サーバー

自然言語を使って Harvest のタイムエントリーを記録できる MCP サーバーです。休暇申請にも特別に対応しています。自然言語での入力を理解し、休暇申請などの一般的なケースを自動で処理することで、より直感的な時間記録を実現します。

特長

• 🗣️ 自然言語によるタイムエントリーの解析
• 🏖️ 休暇申請への特別対応（例：「今日は病気で休みます」）
• ⏰ 1日の勤務時間を設定可能
• 🌍 タイムゾーンに対応
• 🎯 プロジェクトとタスクを自動で照合
• 📅 日付をスマートに解析（今日、昨日など）

前提条件

• Node.js がインストールされていること
• Harvest アカウント
• Harvest Developer Tools から取得した個人用アクセストークン
• アカウント ID（トークンと同じページに表示されています）

インストール

インストール

1. Claude デスクトップアプリをインストールします

2. このリポジトリをクローンします：

git clone https://github.com/adrian-dotco/harvest-mcp-server.git
cd harvest-mcp-server

3. 依存関係をインストールしてビルドします：

npm install
npm run build

4. セットアップスクリプトを実行します：

node build/setup.js

5. プロンプトに従って、次の情報を入力します：

   • Harvest 個人用アクセストークン（https://id.getharvest.com/developers から取得）
   • Harvest アカウント ID
   • 標準の1日の勤務時間（デフォルト：7.5）
   • タイムゾーン（デフォルト：Australia/Perth）

6. Claude デスクトップアプリを再起動します

これで完了です！Claude で自然言語による時間記録を利用できるようになります。

最新版への更新

最新版に更新するには：

git pull
npm install
npm run build

セットアップスクリプトにより、Claude はサーバーのローカルビルドを使用するように設定されています。そのため、更新を取得して再ビルドすれば、更新内容が自動的に反映されます。

使用方法

このサーバーは、Harvest と連携するための複数のツールを提供します：

log_time

自然言語を使ってタイムエントリーを記録します。例：

通常のタイムエントリー：

"2 hours on Project X doing development work today"
"45 minutes on Project Y testing yesterday"
"3.5 hours on Project Z meetings last Friday"

休暇申請（標準の1日の勤務時間を自動で使用）：

"I'm off sick today"
"I'm unwell today"
"Taking annual leave next week"

get_time_report

自然言語でのクエリを使って時間レポートを取得します。例：

1. 期間の指定：

"Show time report for last month"
"Get time summary for this week"
"Show hours from January 1st to January 31st"
"Report time for Q1"
"Show me yesterday's hours"

2. レポートの種類：

• プロジェクト別（デフォルト）：

  "Show time report for last month"
  "Get project hours for this week"
  

• クライアント別：

  "Show time report by client for this month"
  "Get hours by client for Q1"
  

• タスク別：

  "Show time summary by task for January"
  "Get task breakdown for last week"
  

• チームメンバー別：

  "Show team hours for last week"
  "Get time report by user for this month"
  

3. レポートの詳細： 各レポートには次の内容が含まれます：

• 合計勤務時間
• 請求対象時間と請求対象外時間
• 請求額（権限がある場合）
• レポートの種類に応じたプロジェクト／クライアント／タスク／ユーザーの詳細

list_projects

利用可能な Harvest プロジェクトをすべて一覧表示します：

List my projects

list_tasks

特定のプロジェクトで利用可能なタスクを一覧表示します：

Show tasks for Project X

list_entries

最近のタイムエントリーを表示します：

Show my recent time entries

設定

このサーバーでは、次の環境変数を使用できます：

• HARVEST_ACCESS_TOKEN：Harvest 個人用アクセストークン
• HARVEST_ACCOUNT_ID：Harvest アカウント ID
• STANDARD_WORK_DAY_HOURS：標準的な1日の勤務時間（デフォルト：7.5）
• TIMEZONE：タイムゾーン（デフォルト：Australia/Perth）

開発

このサーバーは次の技術を使用して構築されています：

• TypeScript
• MCP SDK
• 自然言語による日付解析用の chrono-node
• Harvest API v2

貢献するには：

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. プルリクエストを送信します

ライセンス

MIT ライセンス。詳細はLICENSEを参照してください。