keeping-mcp

keeping-mcp

Keeping（api.keeping.nl）の時間記録 API を、AI コーディングアシスタントが呼び出せるツールとして公開する、オープンソースの Model Context Protocol（MCP）サーバーです。Claude Code（または MCP 対応クライアント）を使用する個人開発者向けに作られており、セッションの最後に手入力する代わりに、請求対象の作業時間を Keeping に記録できます。また、Keeping の既存の Jortt 請求書連携もそのまま維持されます。書き込みツールはすべてデフォルトでドライランになっており、明示的に確認するまで作業時間が Keeping に送信されることはありません。

⚠ 書き込みはデフォルトでドライランです

書き込みツール（keeping_add_entry、keeping_update_entry、keeping_delete_entry、 keeping_start_timer、keeping_stop_timer、keeping_resume_timer）は、ツールの呼び出しで confirm: true を渡さない限り、プレビューを返します。

環境で KEEPING_REQUIRE_CONFIRM=false を設定すると、この制限が無効になります。 その場合、最初の呼び出しで書き込みが実行され、やり直す機会はありません。

推奨事項：非対話型の自動化環境でサーバーを実行し、確認手順がなくなることを明示的に受け入れている場合を除き、この制限は無効にしないでください。

インストール

npm から

インストールは不要です。初回実行時に npx がパッケージを取得します。

KEEPING_TOKEN=kp_live_your_token_here npx -y keeping-mcp

サーバーは MCP stdio プロトコルを使用し、フォアグラウンドで起動して stdin からの JSON-RPC フレームを待ち受けます。終了するには Ctrl+C を押してください。通常、手動で実行することはありません。MCP 対応クライアント（Claude Code、Claude Desktop、Cursor など）が、以下の設定例を使って起動します。

任意：グローバルにインストールすると、keeping-mcp が PATH に追加されます。

npm install -g keeping-mcp
KEEPING_TOKEN=kp_live_your_token_here keeping-mcp

Node.js >=22 が必要です。パッケージは npmjs.com/package/keeping-mcp で公開されており、sigstore の来歴証明が付属しています。

Windows 11 の Claude Code

%APPDATA%\Claude\claude_desktop_config.json またはプロジェクトの .mcp.json ファイルに追加してください。

{
  "mcpServers": {
    "keeping-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "keeping-mcp"],
      "env": {
        "KEEPING_TOKEN": "kp_live_your_token_here"
      }
    }
  }
}

Windows では cmd /c ラッパーが必要です。npx は npx.cmd に解決されますが、Claude Code のプロセス起動では PATHEXT 拡張子が検索されないためです（anthropics/claude-code#58510 を参照）。

macOS／Linux の Claude Code

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または ~/.config/Claude/claude_desktop_config.json（Linux）、あるいはプロジェクトの .mcp.json に追加してください。

{
  "mcpServers": {
    "keeping-mcp": {
      "command": "npx",
      "args": ["-y", "keeping-mcp"],
      "env": {
        "KEEPING_TOKEN": "kp_live_your_token_here"
      }
    }
  }
}

その他の MCP クライアント

stdio トランスポートをサポートする MCP 対応クライアントであれば、どれでも使用できます。サーバーは npx -y keeping-mcp で起動し、環境から KEEPING_TOKEN を読み取ります。MCP Registry では io.github.Red-Square-Software/keeping-mcp として登録されています。

Keeping アクセストークンの取得

1. Keeping アカウントにサインインします。
2. Preferences（右上のメニュー）を開きます。
3. Show features for developers セクションを見つけ、有効にします。
4. 新しい Personal access tokens セクションが表示されます。
5. Generate new token をクリックし、名前（例：「Claude Code」）を付けて、値をコピーします。
6. シェル環境、または Claude Code の設定の env ブロックに KEEPING_TOKEN として保存します。

このトークンは時間記録への読み取り・書き込みの完全なアクセス権を持つため、パスワードと同様に扱ってください。Git にコミットしたり、チャットに貼り付けたり、ツールの応答から読み返したりしないでください（keeping-mcp がトークンを返すことはありません）。

設定

変数	必須	デフォルト	用途
KEEPING_TOKEN	はい	—	Keeping の個人用アクセストークン（上のセクションから作成します）。
KEEPING_REQUIRE_CONFIRM	いいえ	true	true の場合、confirm: true を指定して呼び出さない限り、書き込みツールはプレビューを返します。false に設定すると、このゲートは完全に無効になります。下の警告をご覧ください。
KEEPING_ORG_ID	いいえ	—	すべての呼び出しを1つの組織 ID に固定します。未設定で、トークンが複数の組織へのアクセス権を持つ場合、書き込みツールでは呼び出しごとに organisation_id の明示的な入力が必要です。
KEEPING_LOG_LEVEL	いいえ	info	サーバーの標準エラー出力に記録するログの詳細度です。指定できる値：debug、info、warn、error。

⚠ 書き込みはデフォルトでドライランです

すべての書き込みツール（keeping_add_entry、keeping_update_entry、keeping_delete_entry、 keeping_start_timer、keeping_stop_timer、keeping_resume_timer）は、ツール呼び出しで confirm: true を渡さない限り、プレビューを返します。

環境変数で KEEPING_REQUIRE_CONFIRM=false に設定すると、このゲートは無効になります。 その場合、最初の呼び出しで書き込みが行われ、やり直す機会はありません。

推奨：非対話型の自動化環境でサーバーを実行していて、確認ステップが失われることを 明示的に受け入れている場合を除き、このゲートは無効にしないでください。

ツール

keeping-mcp は、サーバーの起動時に12個のツールを登録します。読み取りツール（keeping_me、keeping_organisations、keeping_projects、keeping_tasks、keeping_list_entries、keeping_timer_status）は、確認なしで Keeping の API を呼び出します。書き込みツール（keeping_add_entry、keeping_update_entry、keeping_delete_entry、keeping_start_timer、keeping_stop_timer、keeping_resume_timer）は、confirm: true を指定して呼び出さない限り、ドライランのプレビューを返します（デフォルトの動作は KEEPING_REQUIRE_CONFIRM で制御します）。

ドライランのワークフロー（実行例）

書き込みツールは、提案してから確認する2段階のパターンに従います。最初の呼び出しでは、サーバーが送信する HTTP リクエストのプレビューが返されます。2回目の呼び出し（confirm: true を指定）で、実際にリクエストが送信されます。

ステップ1 — プレビュー（confirm の指定なし、API 呼び出しは行われません）。説明用の例です。実際のフィールド名は Keeping の OpenAPI に準拠します（https://developer.keeping.nl を参照）。

{
  "tool": "keeping_add_entry",
  "input": {
    "description": "Phase 4 release prep",
    "hours": 1.5,
    "project_id": 123
  },
  "response": {
    "would_post": {
      "method": "POST",
      "url": "https://api.keeping.nl/v1/456/time-entries",
      "body": {
        "description": "Phase 4 release prep",
        "hours": 1.5,
        "project_id": 123,
        "date": "2026-06-12",
        "purpose": "work"
      }
    }
  }
}

ステップ2 — 確認（confirm: true を追加し、リクエストを Keeping に送信します）。説明用の例です。実際のレスポンス形式は Keeping の OpenAPI に準拠します。

{
  "tool": "keeping_add_entry",
  "input": {
    "description": "Phase 4 release prep",
    "hours": 1.5,
    "project_id": 123,
    "confirm": true
  },
  "response": {
    "id": 98765,
    "day": "2026-06-12",
    "hours": 1.5,
    "description": "Phase 4 release prep",
    "project_id": 123,
    "purpose": "work"
  }
}

来歴の検証

リリースは GitHub Actions の OIDC 信頼済みパブリッシングを通じて公開されます（長期有効な npm トークンは使用しません）。すべてのリリースには、公開された tarball とこのリポジトリ内の特定のコミットを関連付ける npm 来歴証明が付属します。

npm audit signatures
# or, for a single package:
npm view keeping-mcp --json | jq '.dist.attestations'

ローカル開発

git clone https://github.com/red-square-software/keeping-mcp.git
cd keeping-mcp
npm ci
npm test
npm run build
KEEPING_TOKEN=kp_live_your_token_here node dist/bin/keeping-mcp.js

サーバーの出力はすべて標準エラー出力に送られます。標準出力は MCP JSON-RPC のフレーミング用に確保されています。診断情報を標準出力に書き込まないでください。ログには console.error を使用してください。

ライセンス

MIT — LICENSE をご覧ください。