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 전송을 통해 Claude Desktop에 4개의 도구를 노출합니다.

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 내부 도구.