TimeTracker RX MCP サーバー

TimeTracker RX（デンソークリエイト社）の REST API を MCP（Model Context Protocol）サーバーとして公開するツールです。 Claude Code / Claude Desktop / Cursor 等の AI ツールから工数管理・プロジェクト管理・分析を直接操作できます。

セキュリティポリシー: 「人のものを壊さない」 — 自分が管理するリソースのみ書き込みを許可し、他者のプロジェクト・ワークアイテムの破壊を防ぎます。

バージョン履歴

最新版: Ver1.09 (2026-06-26)

Ver	日付	主要変更
Ver1.09	2026-06-26	update_work_item を日付更新・clearSchedule 対応に拡張（planned_start_date/planned_finish_date/fields/clear_schedule/move_schedule_days/field_calc_types/assignment_change/propagate_to_children 追加）、work_item_id→work_item_ids リネームで複数ID一括更新・クリア対応
Ver1.08	2026-06-26	create_project/update_project を公式API準拠に引数拡張（plannedStartDate/plannedFinishDate/managerId/members/projectCategories/memberChange 等）、copy_project 追加、get_project に includes 追加
Ver1.07	2026-05-08	master 系: skip→offset 命名統一 + レスポンス data[] アンラップ。time_entries 一覧に日付・プロジェクト等のサーバ側フィルタ追加
Ver1.06	2026-05-08	acl の引数を公式 ace/aceChange 構造に再設計、analytics の body を公式 filterBy/groups 構造に再設計
Ver1.05	2026-05-07	update_work_item の status_id → status_type_id リネーム + actual_progress 引数追加
Ver1.04	2026-04-27	write 系 body を {fields:{...}} ラッパに統一
Ver1.01〜1.02	2026-04-27	OwnershipChecker のレスポンス形式対応
Ver1.00	2026-04-20	Python + FastMCP 初版リリース

互換性ポリシー: 公式 API 仕様準拠を最優先するため、minor bump (Ver1.0X) でも引数 rename・必須化等の破壊変更を含みます。引数の差分は tests/test_contract.py で自動検知されます。

機能一覧

認証（1）

ツール名	説明
get_me	自分のユーザー情報取得

ユーザー参照（2）

ツール名	説明
list_users	ユーザー一覧取得（読み取り専用）
get_user	ユーザー取得（読み取り専用）

タイムシート — 自分の工数操作（5）

ツール名	説明
list_time_entries	自分の実績工数一覧取得
get_time_entry	自分の実績工数取得
add_time_entry	自分の実績工数追加（他人のプロジェクトへの工数登録も可）
update_time_entry	自分の実績工数更新
delete_time_entry	自分の実績工数削除

タイムシート — 任意ユーザー参照（2）

ツール名	説明
list_user_time_entries	任意ユーザーの実績工数一覧取得（読み取り専用）
get_user_time_entry	任意ユーザーの実績工数取得（読み取り専用）

プロジェクト（7）

ツール名	説明
list_projects	プロジェクト一覧取得（全プロジェクト閲覧可）
get_project	プロジェクト取得（includes で Members/UserGroups/WorkCalendar を指定可）
create_project	プロジェクト作成（plannedStartDate/plannedFinishDate 等の公式項目・メンバー対応、管理者は未指定で自分）
update_project	プロジェクト更新（日付・メンバー変更等の公式項目対応、自分が管理者のPJのみ）
copy_project	既存プロジェクトの設定・メンバーをコピーして新規作成
get_project_calendar	プロジェクトカレンダー取得
get_project_profile	プロジェクトプロファイル取得

ワークアイテム（6）

ツール名	説明
list_sub_items	サブアイテム一覧取得
get_work_item	ワークアイテム取得
create_work_item	ワークアイテム追加（自分が管理者のプロジェクトのみ）
update_work_item	ワークアイテム更新（予定日更新・clearSchedule によるクリア・複数ID一括対応、自分が管理者のプロジェクトのみ）
delete_work_item	ワークアイテム削除（自分が管理者のプロジェクトのみ、アトミック拒否）
duplicate_work_item	ワークアイテム複製（自分が管理者のプロジェクトのみ）

ACL — プロジェクト権限（4）

ツール名	説明
get_project_acl	プロジェクト権限取得（全プロジェクト閲覧可）
add_project_acl	プロジェクト権限追加（自分が管理者のプロジェクトのみ）
update_project_acl	プロジェクト権限更新（自分が管理者のプロジェクトのみ）
delete_project_acl	プロジェクト権限削除（自分が管理者のプロジェクトのみ）

マスタ参照（7）

ツール名	説明
list_item_types	アイテムタイプ一覧
list_status_types	ステータスタイプ一覧
list_process_categories	工程分類一覧
list_time_entry_categories	作業分類一覧
list_field_types	フィールドタイプ一覧
list_organizations	組織一覧
list_profiles	プロファイル一覧

分析（3）

ツール名	説明
analyze_time	工数分析（全ユーザー対象可）
analyze_item_counts	アイテム件数分析（全ユーザー対象可）
export_time_entries	実績工数エクスポート

セットアップ

前提条件

• Python 3.12 以上
• uv（curl -LsSf https://astral.sh/uv/install.sh | sh などでインストール）
• TimeTracker RX の API キー（管理画面のユーザー設定から発行）

インストール

MCP クライアントごとに最適な方式を使い分けます。

環境	方式	理由
Claude Code (WSL/Linux/macOS)	uvx (on-demand)	事前インストール不要、タグ変更即反映
Cursor (Windows / macOS)	uvx (on-demand)	同上
Claude Desktop / Cowork (Windows MSIX)	pre-install	MSIX sandbox が spawn 子プロセスからの git fetch を拒否するため

uvx 方式（Claude Code / Cursor）:

# 動作確認
TIMETRACKER_BASE_URL=https://your-server/TimeTrackerRX/ \
TIMETRACKER_API_KEY=your-key \
uvx --from git+https://github.com/nori1173-ops/timetracker-rx-mcp@Ver1.09 timetracker-rx-mcp

pre-install 方式（Claude Desktop）:

Windows PowerShell で事前にインストール:

uv tool install git+https://github.com/nori1173-ops/timetracker-rx-mcp@Ver1.09 --force

インストール先: %USERPROFILE%\.local\bin\timetracker-rx-mcp.exe。以降は timetracker-rx-mcp コマンドとして実行可能。

バージョン指定:

• 本番利用: @Ver1.09 のようにタグ固定を推奨（破壊変更から保護される）
• 開発版: @master で常に最新を追う（破壊変更の可能性あり）

更新:

• uvx 方式: uv cache clean で再取得
• pre-install 方式: uv tool upgrade timetracker-rx-mcp --force

環境変数

MCP 設定ファイルの env セクションで環境変数を指定します。

変数名	必須	説明	例
TIMETRACKER_BASE_URL	必	TimeTracker RX の API ベース URL	https://your-server/TimeTrackerRX/
TIMETRACKER_API_KEY	必	ユーザーの API キー	your-api-key
TIMETRACKER_TIMEOUT_MS	任	リクエストタイムアウト（ミリ秒、既定 30000）	60000
TIMETRACKER_SKIP_TLS_VERIFY	任	自己署名証明書向け TLS 検証スキップ（既定 false）	true

MCP 設定

全環境共通で uvx --from git+https://github.com/nori1173-ops/timetracker-rx-mcp@Ver1.09 timetracker-rx-mcp を呼び出します。

Claude Code（WSL/Linux/macOS）

~/.claude.json の mcpServers に追記します。

{
  "mcpServers": {
    "timetracker-rx": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/nori1173-ops/timetracker-rx-mcp@Ver1.09",
        "timetracker-rx-mcp"
      ],
      "env": {
        "TIMETRACKER_BASE_URL": "https://your-server/TimeTrackerRX/",
        "TIMETRACKER_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktop / Cowork（Windows MSIX 環境）

MSIX sandbox で git fetch が失敗するため pre-install 方式を使います。事前に uv tool install を実行しておく必要があります（上記「インストール」参照）。

%APPDATA%\Claude\claude_desktop_config.json の mcpServers に追記:

{
  "mcpServers": {
    "timetracker-rx": {
      "command": "timetracker-rx-mcp",
      "env": {
        "TIMETRACKER_BASE_URL": "https://your-server/TimeTrackerRX/",
        "TIMETRACKER_API_KEY": "your-api-key"
      }
    }
  }
}

新バージョン（Ver1.01 等）リリース時は uv tool upgrade timetracker-rx-mcp --force を PowerShell で別途実行してください（Claude Desktop は自動更新されません）。

Cursor（Windows / macOS）

{
  "mcpServers": {
    "timetracker-rx": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/nori1173-ops/timetracker-rx-mcp@Ver1.09",
        "timetracker-rx-mcp"
      ],
      "env": {
        "TIMETRACKER_BASE_URL": "https://your-server/TimeTrackerRX/",
        "TIMETRACKER_API_KEY": "your-api-key"
      }
    }
  }
}

自己署名証明書の環境では env に "TIMETRACKER_SKIP_TLS_VERIFY": "true" を追加してください。

セキュリティポリシー

「人のものを壊さない」 — このルールはすべての実装に優先します。

操作	制限
閲覧（GET）	全て許可。他者のリソースも読み取り可
プロジェクト作成	管理者（managerId）は自分に自動設定
プロジェクト更新	自分が管理者のプロジェクトのみ
ワークアイテム CRUD	自分が管理者のプロジェクトのみ
ACL 変更	自分が管理者のプロジェクトのみ
タイムシート操作	自分のユーザー ID のみ（他者分は閲覧のみ可）
分析（読み取り）	全ユーザーのデータを含めて許可
ユーザー管理	一覧・取得のみ実装（作成・更新・削除は除外）

複数 ID の一括操作では、1 つでも権限のない対象が含まれる場合は操作全体を拒否します（アトミック拒否）。

開発

セットアップ

uv sync --extra dev

テスト

uv run pytest                    # 全テスト
uv run pytest --cov              # カバレッジ付き
uv run pytest tests/test_ownership.py -v  # 単一ファイル

lint / format

uv run ruff check src/ tests/
uv run ruff format src/ tests/

ローカル実行

export TIMETRACKER_BASE_URL=https://your-server/TimeTrackerRX/
export TIMETRACKER_API_KEY=your-key
uv run timetracker-rx-mcp

技術スタック

• Python 3.12+
• mcp（FastMCP）
• httpx（HTTP クライアント、コネクションプール）
• pydantic（バリデーション）
• uv（パッケージ管理）
• ruff（lint + format）
• pytest / pytest-asyncio / respx（テスト）

アーキテクチャ

詳細は Documents/DESIGN.md を参照してください。

ライセンス

MIT

免責事項

• 本プロジェクトはデンソークリエイト社とは無関係の非公式ツールです。
• TimeTracker RX の正規ライセンスが別途必要です。
• API の仕様変更により動作しなくなる可能性があります。
• 本ツールの使用により発生した損害について開発者は責任を負いません。

商標

「TimeTracker」はデンソークリエイト株式会社の登録商標です。