projectx-mcp

Claude Desktopと会話してProjectXに工数を記録します。

「今日のOntracに8時間記録して」 「今週の未入力の日をOntracで埋めて」 「今月、工数が入力されていない日はいつ？」

インストール

macOS (自動)

git clone git@github.com:agustindiezdb/projectx-mcp.git
cd projectx-mcp
bash scripts/install.sh

このスクリプトは以下の処理を行います：

• 依存関係のインストール

• プロジェクトのビルド

• Claude Desktopの自動設定

• 既存設定のバックアップ作成

その後、Claude Desktopを再起動してください。DualbootのGoogleアカウントでログインするためにChromeが自動的に開きます。

以上です！ これでClaudeに工数を記録するよう依頼できます。

Windows

git clone git@github.com:agustindiezdb/projectx-mcp.git
cd projectx-mcp
npm install
npm run build

次に、Claude Desktopの設定を手動で編集します：

以下を開きます：%APPDATA%\Claude\claude_desktop_config.json

以下を追加します：

{
  "mcpServers": {
    "projectx": {
      "command": "node",
      "args": ["C:\\full\\path\\to\\projectx-mcp\\dist\\src\\server.js"]
    }
  }
}

C:\full\path\to\ を実際のパスに置き換えてください（Windowsのパスには \ を使用してください）。

その後、Claude Desktopを再起動してください。ログインのためにChromeが自動的に開きます。

手動インストール

手動で設定したい場合：

1. クローンとビルド：

   git clone git@github.com:agustindiezdb/projectx-mcp.git
   cd projectx-mcp
   npm install
   npm run build

2. Claude Desktopの設定を編集：
   ~/Library/Application Support/Claude/claude_desktop_config.json を開き、以下を追加します：

   {
     "mcpServers": {
       "projectx": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/TO/projectx-mcp/dist/src/server.js"]
       }
     }
   }

   /ABSOLUTE/PATH/TO/ をクローンしたリポジトリへのフルパスに置き換えてください。

3. Claude Desktopを再起動

Cursorでの使用

CursorはプロジェクトごとのMCP設定を使用します。プロジェクトのルートに .cursor/mcp.json を作成してください：

{
  "$schema": "https://json.schemastore.org/mcp.json",
  "mcpServers": {
    "projectx": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/projectx-mcp/dist/src/server.js"]
    }
  }
}

/ABSOLUTE/PATH/TO/ をクローンしたリポジトリへのフルパスに置き換えてください。

その後、Cursorを再起動してください。初回起動時にログイン用のChromeが開きます。

使用方法

Claudeに自然な言葉で話しかけるだけです：

Log 8 hours of Ontrac for today with description "Sprint planning"

Check my entries for this week and fill the missing days with 8h of Ontrac

Delete yesterday's entry and log 4h of Internal — Administrative

Which days am I missing hours for April?

利用可能なツール

ログインに失敗した場合やセッションが切れた場合

Claude Desktopを再起動するだけです。ログインのためにChromeが再度開きます。

便利なスクリプト

Claude Desktopを使わずに直接APIを利用することも可能です：

# Test the API (creates and deletes a test entry)
npm run test:entry

# Check which days you're missing hours in April
npx ts-node scripts/check-april.ts

# Manually refresh your session (if expired)
npm run save-session

開発者向け

アーキテクチャ

Claude Desktop → MCP Server (stdio) → fetch() + _interslice_session cookie → ProjectX API

セッションクッキーは ~/Library/Application Support/projectx-mcp/auth.json (gitignored) に保存されます。

起動時に有効なセッションが見つからない場合、Playwright経由でログイン用のChromeが自動的に開きます。

開発モード

npm run dev

これは迅速な開発のために ts-node でサーバーを実行します（ビルド手順は不要です）。

仕組み

1. 認証: Playwrightを使用してChromeを開き、/api/v1/current_user をポーリングすることでログイン成功を自動検知します

2. セッションの永続化: Playwrightの storageState() を使用してクッキーを auth.json に保存します

3. APIクライアント: _interslice_session クッキーを読み取り、ProjectXに対して認証済みリクエストを行います

4. MCPプロトコル: stdioトランスポートを介して4つのツールをClaude Desktopに公開します

Claude Desktopの設定（手動）

手動で編集したい場合：

{
  "mcpServers": {
    "projectx": {
      "command": "node",
      "args": ["/path/to/projectx-mcp/dist/src/server.js"]
    }
  }
}

トラブルシューティング

• セッション期限切れ → Claude Desktopを再起動するとChromeが自動的に開きます

• Chromeが見つからない → Google Chromeをインストールしてください（システムPATHに含まれている必要があります）

• プロジェクトが見つからない → Claudeに get_projects を実行させて正確な名前を確認してください

• パスの問題 (macOS/Linux) → ~ や相対パスではなく、絶対パスを使用してください

• パスの問題 (Windows) → JSONパス内では \ (ダブルバックスラッシュ) を使用してください（例: C:\Users\...）

• 認証ファイルの場所:

  • macOS: ~/Library/Application Support/projectx-mcp/auth.json

  • Windows: %APPDATA%\projectx-mcp\auth.json

  • Linux: ~/.config/projectx-mcp/auth.json

要件

• OS: macOS, Windows, または Linux

• Node.js: 20以上

• ブラウザ: Google Chrome (自動ログインに必須)

• Claude Desktop

• Dualboot Googleアカウント

ライセンス

Dualboot Partnersの社内ツール。