@nicola5tor/openproject-timelog

MCPサーバー（Model Context Protocol）で、ローカルの時間記録を管理し、OpenProject（API v3）と同期します。Claude Desktop（または他のMCPクライアント）から自然言語で作業を記録し、確認して、準備ができたらOpenProjectにアップロードします。

• トランスポート: stdio

• ローカルストレージ: ~/.openproject-timelog/entries.json

• 設定: 環境変数 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認証を行います。

ローカルのみのツール（log_entry, list_entries, edit_entry, assign_entry, delete_entry, clear_sent）はOpenProjectを設定しなくても動作します。クエリおよびアップロードのツールには OPENPROJECT_URL と OPENPROJECT_API_KEY が必要です。

ツール

ローカル記録

OpenProjectのクエリ

同期

* = 必須。

動作に関する注意事項

• ローカルIDはUUID v4です。時間は10進数（1.5 = 1時間30分）で保存され、アップロード時にISO 8601の期間（PT1H30M）に変換されます。

• エントリの projectId は、指定されない場合、アップロード時にワークパッケージから推定されます（OpenProjectへの追加呼び出し）。

• JSONファイルはアトミックに書き込まれ（一時ファイル＋リネーム）、破損を防ぐために操作は直列化されます。

• ネットワーク/資格情報/権限のエラーは、サーバーを停止させることなく、ツールの応答で読み取り可能なメッセージとして返されます。

会話での使用例

あなた: 今日のログイン修正の2時間を記録して、タスク1234。 Claude: (log_entry を description="ログイン修正", hours=2, workPackageId=1234 で呼び出し)

あなた: 45分の会議を記録しておいて、タスクは後で設定するから。 Claude: (log_entry description="会議", hours=0.75) — 未割り当てのまま。

あなた: 何をアップロード待ちにしていますか？ Claude: (list_entries status="pending")

あなた: その2つの会議にタスク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