@nicola5tor/openproject-timelog

MCP 서버(Model Context Protocol)는 로컬 시간 기록부를 관리하고 이를 OpenProject(API v3)와 동기화합니다. Claude Desktop(또는 다른 MCP 클라이언트)에서 자연어로 작업을 기록하고, 검토한 후 준비가 되면 OpenProject에 업로드하세요.

• Transport: stdio

• 로컬 저장소: ~/.openproject-timelog/entries.json

• Config: 환경 변수 OPENPROJECT_URL 및 OPENPROJECT_API_KEY

설치

전역으로 설치할 필요가 없습니다. 서버는 npx로 실행됩니다.

# probarlo directamente
npx @nicola5tor/openproject-timelog

또는 프로젝트에 설치하려면:

npm install @nicola5tor/openproject-timelog
# o
pnpm add @nicola5tor/openproject-timelog

Related MCP server: OpenProject MCP Server

Claude Desktop에서 설정

설정 파일(claude_desktop_config.json)을 편집하고 mcpServers 아래에 서버를 추가하세요:

{
  "mcpServers": {
    "openproject-timelog": {
      "command": "npx",
      "args": ["-y", "@nicola5tor/openproject-timelog"],
      "env": {
        "OPENPROJECT_URL": "https://tu-openproject.example.com",
        "OPENPROJECT_API_KEY": "TU_API_KEY"
      }
    }
  }
}

저장 후 Claude Desktop을 다시 시작하세요.

OpenProject API 키 얻는 방법

OpenProject에서: 내 계정 → Access tokens → API 로 이동하여 키를 생성하세요. 서버는 리터럴 사용자 apikey와 키를 비밀번호로 사용하여 Basic auth로 인증합니다.

로컬 전용 도구(log_entry, list_entries, edit_entry, assign_entry, delete_entry, clear_sent)는 OpenProject를 구성하지 않아도 작동합니다. 조회 및 업로드 도구는 OPENPROJECT_URL과 OPENPROJECT_API_KEY가 필요합니다.

도구

로컬 기록부

OpenProject 조회

동기화

* = 필수.

동작 참고 사항

• 로컬 id는 UUID v4입니다. 시간은 십진수(1.5 = 1h30m)로 저장되며 업로드 시 ISO 8601 기간(PT1H30M)으로 변환됩니다.

• 항목의 projectId는 지정하지 않으면 업로드 시 work package에서 파생됩니다 (OpenProject에 대한 추가 호출).

• JSON 파일은 원자적으로(임시 파일 + rename) 작성되며, 손상을 방지하기 위해 작업이 직렬화됩니다.

• 네트워크/자격 증명/권한 오류는 서버를 중단시키지 않고 도구 응답에서 읽을 수 있는 메시지로 반환됩니다.

대화형 사용 예시

사용자: 오늘 로그인 수정 작업 1234에 2시간 기록해 줘. Claude: (log_entry를 description="로그인 수정", hours=2, workPackageId=1234로 호출)

사용자: 회의 45분 기록해 줘, 작업은 나중에 정할게. Claude: (log_entry description="회의", hours=0.75) — 할당 대기 상태로 남습니다.

사용자: 업로드 대기 중인 항목이 뭐가 있어? Claude: (list_entries status="pending")

사용자: 그 회의 두 개에 작업 1234를 할당해 줘. Claude: (assign_entry entryIds=[...], workPackageId=1234)

사용자: 어떤 활동이 있어? 전부 "Development"로 설정하고 업로드해 줘. Claude: (get_activities → edit_entry/assign으로 activityId 설정 → upload_entries)

사용자: 이미 업로드된 것 정리해 줘. Claude: (clear_sent)

개발

npm install      # instala deps y compila (prepare -> build)
npm run build    # compila TypeScript a dist/
npm start        # ejecuta dist/index.js

구조:

openproject-timelog/
├── src/
│   ├── index.ts        # entry point, setup MCP y registro de tools
│   ├── store.ts        # CRUD bitácora local (JSON atómico)
│   ├── openproject.ts  # cliente API OpenProject v3
│   └── types.ts        # interfaces/types
├── package.json
├── tsconfig.json
└── README.md

라이선스

MIT