Harvest Time Tracking MCP Server

Harvest Time Tracking MCP サーバー

Harvest の時間追跡アプリ向けに TypeScript で構築された MCP（Model Context Protocol）サーバーです。LLM クライアントが Harvest アカウントを操作できます。

インストール

npx -y @mayankg0324/mcp-server-harvest

前提条件

• Node.js >= 18（または開発用の Bun Runtime）
• API アクセスが有効な Harvest アカウント
• Harvest の API Personal Access Token
• Harvest のアカウント ID

Personal Access Token の作成方法について詳しくは、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 を見つけられない場合に発生します。GUI アプリケーションは、特に nvm、fnm、volta などのバージョン管理ツールを使用している場合、シェルの PATH を引き継がないことがよくあります。

解決方法： 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
   

   コンパイル済みの JavaScript ファイルを含む dist ディレクトリが作成されます。

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