Amazing Marvin (complete)

amazing-marvin-complete-mcp

Amazing Marvin 用の MCP（Model Context Protocol）サーバーです。Marvin のAPI エンドポイント一覧ページに記載された 38 個のエンドポイント（2026-10-12 に確認。以下の 2 つを除く）に対し、公開 API を完全に網羅する 50 個のツールを提供します。Marvin が公開している制限を遵守するグローバルレートリミッター、最小権限のトークンルーティング、MCP ツールアノテーションも備えています。1.1.0 以降、Marvin の公式データモデル（タスクとカテゴリー／プロジェクト）の書き込み可能なフィールドはすべて、ツールでサポートされているか、未サポートであることが明示的に文書化されています。詳しくはdocs/field-reconciliation.mdをご覧ください。ツールの説明に記載された、明白でない挙動に関する主張はすべてライブ API で検証済みです。調査結果は以下のMarvin API の特記事項と調査結果に記載しています。このサーバーを実行しない場合でも参考になるかもしれません。

メンテナンス状況： バグ報告は歓迎しており、寄せていただけると助かります。皆さんが問題なく使い続けられるよう役立てています。ただし、これは時間があるときにメンテナンスしている個人プロジェクトです。バグ報告には目を通しますが、対応までの時間はさまざまで、機能リクエストに対応できる可能性は低いです。インストール方法については、この README を AI アシスタントに貼り付けてください。私が対応するよりずっと速く、セットアップやトラブルシューティングを案内できます。無保証で現状のまま提供しています。MIT ライセンスですので、ご自由にフォークしてください。

ツール（50）

グループ	ツール
コア	test_connection, create_task, mark_done, mark_project_done, unmark_done, update_task, set_priority, delete_task
読み取り	get_today_items, get_due_items, get_done_items, get_children, get_categories
繰り返しタスク	create_recurring_task, update_recurring_task
ノートブック	get_notebooks, get_notebook, search_notebooks, create_notebook, update_notebook, delete_notebook, create_notebook_page, update_notebook_page, delete_notebook_page
構造	create_category_or_project, update_category_or_project, convert_category_or_project（実験的）
習慣	list_habits, get_habit, record_habit
タイムブロック	get_today_time_blocks, create_time_block（実験的）
時間記録	get_tracked_item, start_tracking, stop_tracking, get_time_tracks
Kudos／報酬	get_kudos, claim_reward_points, unclaim_reward_points, spend_reward_points, reset_reward_points
その他	get_labels, get_goals, get_reminders, set_reminder, delete_reminder, create_event（実験的）, get_account_info, get_rate_limit_status, list_capabilities

機能の概要

list_capabilities（Marvin API の呼び出しなし）は、以下の表と同じマップを返します。各ツールについて「できること」と「できないこと」に加え、アプリ内でのみ利用できる機能の一覧も含まれます。MCP では不可能だと思い込む前に呼び出してください。また、サーバーは initialize 時に短い instructions テキストも送信します（Claude Code には表示されますが、claude.ai クライアントには表示されません）。すべてのツール説明の最初の行は、機能を示す 75 文字以内の完結した文です。クライアントのカタログに表示されるのはこの行だけです。テスト tests/test_discoverability.py でこれを保証しています。同じテストにより、すべての説明と instructions テキストを 2,048 文字未満に保っています。Claude Code は v2.1.280 以降、長いテキストを通知なく切り詰めます。

分野	MCP でできること	MCP ではできないこと（アプリ内で実行）
タスク	作成／更新／完了／削除、優先度と frog 1～4、サイズ、サブタスク、時刻とアプリのフォームで設定する独自のリマインダー、日付、期限、ラベル、見積もり、メモ、セクション、計画する週／月、レビュー日、後回し、軌道、スヌーズ、時間ブロック、未完了のタスクがあるプロジェクトの完了（2 ステップ）、アプリに表示されるとおりに今日のタスク、期限超過のタスク、完了済みのタスクを読み取り、フィルタリング	作成時の startDate（その後 update_task で更新）、すでに存在する繰り返し項目の修正、完了済みプロジェクトの再開
繰り返しタスク	11 種類すべての作成（カスタムは RRULE 文字列のみ）、ルール／期間／配置／プロパティの変更、条件に合わなくなった繰り返し項目の整理（一覧表示、確認）	繰り返しタスクのリマインダー／frog、繰り返しプロジェクト、単語で指定するカスタムルール
ノートブック	一覧表示、読み取り、検索、作成、名前変更、セクション、ページ：作成／編集／移動／削除、2 ステップでのノートブック削除	元に戻す（API 経由のゴミ箱はありません）
構造	階層、子要素、カテゴリーとプロジェクトの作成／更新／変換、両方へのラベル付け、色、アイコン、メモ、ラベルと目標の読み取り	ラベル、目標、スマートリスト、ストラテジーの作成／編集
習慣	一覧表示、記録の追跡、記録／取り消し。習慣のタスクは mark_done で記録され、unmark_done で取り消されます	習慣の作成／編集
時間	今日の時間ブロックとマッピング、ブロックの作成、時間追跡の開始／停止／履歴	ブロック上のスマート時間ブロックのマッピング
報酬	kudos、報酬ポイントの付与／取り消し／使用／リセット	MANUAL の付与の取り消し、アプリの「報酬」の読み取り
リマインダー	タスク独自のリマインダー（一覧表示＋サーバーエントリー）、単独のリマインダー、削除、update_task による時刻の設定	—
カレンダー	イベントの作成（試験的）	イベントの読み取り／編集
アカウント	テスト、アカウント情報、呼び出し上限、機能の概要	—

意図的に含めていないもの：スマートリスト／タスク選択ロジック（Marvin 独自の Spotlight が選択を行います。サーバーがアシスタントに渡すのは操作手段であり、意見ではありません）。また、ツールを用意していない、ドキュメント化された 2 つのエンドポイントも含めていません。/reminder/deleteAll は 1 回の呼び出しですべてのリマインダーを消去するため、意図的に除外しています。対象を絞った整理には delete_reminder をすでに利用できます。もう 1 つは /downloadAttachment です（添付ファイルには対応していません）。

すべてのツールには MCP ツールアノテーション（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）が付いているため、対応クライアントは delete_task や reset_reward_points を適切に扱えます。

Marvin トークンの取得

どちらのトークンも Amazing Marvin の Settings → API (app.amazingmarvin.com/pre?api) にあります。

• API Token（MARVIN_API_TOKEN、使用に必須）— アクセスは制限されていますが、タスクの読み取りと作成には十分です。トークンなしでもサーバーは起動します（そのため、MCP クライアントやディレクトリではツールの一覧を表示できます）が、トークンを設定するまではすべてのツール呼び出しで明確なエラーが返されます。
• Full Access Token（MARVIN_FULL_ACCESS_TOKEN、任意ですが推奨）— /doc* ベースのすべてのツールで必要です：update_task、set_priority、unmark_done、delete_task、カテゴリの作成、タイムブロック、list_habits、リマインダー、reset_reward_points。

パスワードと同様に取り扱ってください。SECURITY.md を参照してください。

インストールと実行

Python 3.12 以降が必要です。

PyPI から（推奨）：uv がインストールされていれば、セットアップは不要です。以下に示すように、MCP クライアントから uvx amazing-marvin-complete-mcp を指定してください。

ソースから：

git clone <this repo> && cd amazing-marvin-complete-mcp
python -m venv .venv && .venv/bin/pip install .
# then use /path/to/.venv/bin/marvin-mcp as the command below

ローカル（stdio）— Claude Desktop、Claude Code、任意の MCP クライアント

デフォルトのトランスポートは stdio なので、クライアントがサーバーを起動します。

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "uvx",
      "args": ["amazing-marvin-complete-mcp"],
      "env": {
        "MARVIN_API_TOKEN": "…",
        "MARVIN_FULL_ACCESS_TOKEN": "…",
        "MARVIN_TIMEZONE": "Europe/Stockholm"
      }
    }
  }
}

（Claude Code の場合：claude mcp add amazing-marvin -e MARVIN_API_TOKEN=… -- uvx amazing-marvin-complete-mcp。）

リモート（Streamable HTTP）

MCP_TRANSPORT=http PORT=8787 MCP_AUTH_TOKEN_FILE=/path/to/token \
MARVIN_API_TOKEN_FILE=/path/to/api-token .venv/bin/marvin-mcp

MCP エンドポイントは /mcp です。HTTP モードはフェイルクローズです。MCP_AUTH_TOKEN（または MCP_AUTH_TOKEN_FILE）がない場合、サーバーはエラーメッセージ内の手順を示して起動を拒否します。ローカルホスト上で意図的にオープンなインスタンスを実行する場合に限り、MCP_ALLOW_UNAUTHENTICATED=true を設定してください。組み込みのベアラーチェックはすべてのパスを保護しますが、内部的な防壁であり、認証の仕組みとして完全ではありません。 前段に TLS 対応のリバースプロキシを置き、Claude のカスタムコネクターには OAuth 2.1 対応の MCP 認証プロキシを使用してください。HTTP モード用の Dockerfile が含まれています（非 root ユーザーとして実行されます。再起動後も日次レート制限カウンターを保持するには、/data にボリュームをマウントしてください）。

設定

設定はすべて環境変数で行います。注釈付きの設定一覧については .env.example を参照してください。主なポイント：すべてのシークレットには *_FILE 版があり、これを推奨します。MARVIN_TIMEZONE は Marvin アカウントのタイムゾーンに合わせてください（デフォルトはシステムのタイムゾーンで、ほとんどのコンテナーでは UTC です）。

レート制限

Marvin が公開している制限（3 秒に 1 回を超えるバーストは禁止、一括作成は毎秒 1 件、1 日 1440 回）は、すべてのツールとセッションで共有される単一のプロセス全体キューによって、余裕を持たせて適用されます。作成呼び出し（/addTask、/addProject、/addEvent、/doc/create）は 1.1 秒間隔で、それ以外（読み取り、更新、/markDone、削除）は 3.1 秒間隔で待機します。間隔は、これから実行する呼び出しの種類によって決まります。429 が返された場合、すべての呼び出しは 60 秒間（または Retry-After の指定時間）停止します。日次カウンターと最後の呼び出し時刻は再起動後も保持され（STATE_DIR）、カウンターは設定されたタイムゾーンの午前 0 時にリセットされます。get_rate_limit_status では、本日の使用量と最後の呼び出しからの経過時間を確認できます。複数ステップのツール（チェーン）は、500 または 429 の後にステップを 1 回再試行し、それでも失敗した場合は完了したステップを報告します。

Marvin API の仕様と調査結果

以下はすべて、ライブ API で検証済みです（2026-08-19 から 2026-10-12 まで）。このリポジトリのうち、実行せずに利用できる部分です。

習慣

• raw ではない GET /habits は、習慣のドキュメントを読み取りません。初回の記録時に遅延作成されるサーバー側の追跡レジストリーを読み取ります。そのため、記録されたことのない習慣はレスポンスにまったく含まれず、項目にタイトルはなく（habitId と履歴のみ）、?raw=1（Full Access Token）を使うと実際の習慣ドキュメントを一覧表示できます。GET /habit?id=… は追跡レコードを返します。履歴はありますが、タイトルはありません。
• POST /updateHabit は、浮動小数点数としてシリアライズされた整数を拒否します： "value": 1.0 → 400 Bad request、"value": 1 → 200。整数は整数として送信してください。 タスクとプロジェクト
• POST /markDone はタスクにのみ機能します。プロジェクトの場合は 400 "Can only mark Tasks done with this API" が返されます。
• デフォルトでは、/addTask は Marvin のクイック追加ショートカット構文の 一部をサーバー側で解析します。~15 は 15 分の timeEstimate になり、 +YYYY-MM-DD は day（スケジュール設定 — 期限ではありません）を設定し、 *p1..*p3 は優先度を設定します。3 つともタイトルから削除されます。 優先度のマッピングは保存フィールドとは逆になっている点に注意してください。 *p1（最高）→ isStarred: 3、*p2 → 2、*p3（最低）→ isStarred: 1。 それ以外のマジックワード（*urgent、 *fire、*heavy、*weight、*love、*lowfocus、*physical）と $ で始まる語（例：繰り返しタスクではないタスクの $MONTH）は 解析されません。フィールドは設定されず、タイトルに文字列のまま保存されます。 これらが機能するのはアプリのクイック追加だけです。 ただし、# ショートカットは明らかに危険です。タイトル内の あらゆる #word（#123 のようなチケット参照も含む）が、 ID の解決なしに文字列のまま parentId として保存されます（最初のハイフンまで 貪欲に取得されるため、例：#MCP-TEST → parentId: "#MCP" となり、タイトルも破損します）。 同じリクエストで明示的に指定した parentId さえ上書きされます。 そのタスクはすべてのカテゴリーの外、かつ Inbox の外に置かれ、 実質的に見えなくなります。（最初の報告は lucasoeth/marvin-mcp。 ここで独立して再現し、詳細も確認しました。） このサーバーは影響を受けません。 create_task は、文書化されていない X-Auto-Complete: false ヘッダー（ MarvinAPI#50 で追加）を送信し、すべてのショートカット解析を無効にします。タイトルは そのまま保存され、time_estimate_minutes パラメーターが ~15 ショートカットの代わりになります（timeEstimate はミリ秒です： 15 分 = 900000）。
• /addProject にも同じ #word 破損バグがありますが、 X-Auto-Complete ヘッダーを無視します（実環境でテスト済み： ヘッダーを設定してもタイトルは削除され、parentId は破損します）。 そのため、このサーバーはプロジェクトのタイトルに含まれる # を ローカルで（API 呼び出し前にクライアント層で）ブロックし、説明付きの エラーを返します。カテゴリーのタイトルは安全です。何も解析しない /doc/create を経由するためです。
• /addEvent は影響を受けません（2026-08-25 に実環境でテスト済み）。 #word を含むイベントのタイトルは、ヘッダーの有無にかかわらずそのまま 保存されます。クイック追加の解析バグが存在するのは /addTask と /addProject だけです。
• 繰り返しタスクの生成インスタンスには決定的な ID （YYYY-MM-DD_<recurringTaskId>）が割り当てられます。そのため、API 経由で 完了または未完了にしても重複は作成されません。インスタンスを生成するのは Marvin のクライアントです。そのため、アプリの起動後しばらくするまで、 今日の繰り返しタスクが /todayItems に表示されないことがあります。
• /doc/update は一時的な 500 をまれに返すことがあります。書き込みは アトミック（部分的な状態にはなりません）なので、再試行してください。 プロジェクトの名前変更、移動、ラベルの変更などはすべてこのエンドポイントで 機能します。
• /doc/update は存在しないドキュメント（削除済み、または未作成のもの。 2026-08-29 に実環境でテスト済み）に対して 404 ではなく 500 を返します。 そのため、恒久的な 500 はサーバーエラーやドキュメントの破損ではなく、 「ID が間違っているか、無効である」ことを意味します。
• /addTask と /addProject は startDate/endDate を無視します （2026-08-29 に実環境でテスト済み）。これらは後から /doc/update（更新ツール）でのみ設定できます。/addProject は color/icon も無視します（update_category_or_project で設定）。 また、/addTask は noAutoOrbit を黙って破棄します （2026-09-13 に実環境でテスト済み）。タスクの作成後に update_task で 設定してください。
• タスクの時刻（Time／taskTime）は Marvin で完全にサポートされており、 リマインダーが自動作成される場合、Time を設定すると同じ時刻のリマインダーが 自動的に作成されます（2026-09-02 の実データ）。1.8.0 まではこの設定を アプリに任せていましたが、1.8.0 以降、ツールはアプリ独自の形式で書き込みます （フィールドとサーバーエントリーをまとめて設定します。下記の リマインダーと時刻を参照してください）。
• プロジェクトの優先度には、タスクの isStarred ではなく文字列フィールドの priority（"high"/"mid"/"low"）が使われます （2026-08-29 に実環境でテスト済み）。このため、set_priority は タスク専用です。マッピング（2026-08-30 にアプリのコードと照合して確認済み）： high = 最重要（赤）、mid = 非常に重要（オレンジ）、low = 重要 （黄色、星 1 つのレベル）。アプリの 4 番目のレベルである優先度低（下矢印）は、 タスクでは isStarred: -1（マジックワード *low/*p0）として保存されます。 プロジェクトにはこのレベルがありません。優先度の低いタスクをプロジェクトに 変換すると、アプリは優先度をクリアします。set_priority/create_task は -1 を受け付けます。
• 完了したタスクは読み取り可能です。文書化されていないエンドポイント GET /doneItems?date=YYYY-MM-DD を使用します（OpenAPI 仕様と Wiki には 記載されていません。2026-08-30 に実環境でテスト済み。予告なく使えなくなる 可能性があります）。これは doneAt ではなく、タスクの day で絞り込みます。 過去の day は完了後もアプリと /markDone の両方で保持されます （アプリが day を今日に設定するのは、スケジュールされていないタスクと 未来の日付のタスクのみです）。そのため、get_done_items は対象日と過去 7 日間を 取得して doneAt で絞り込みます。レスポンスには対象範囲 （covers_from、days_fetched）が示され、完全な結果は 30 分間キャッシュされます。 429 の場合、ツールは取得できた内容を incomplete/days_missing のフラグ付きで 返します。完了したタスクを個別に読み取るには /doc?id= も使えます。 /todayItems、/dueItems、/children は完了済み項目を除外します。 /doneTasks と /completedItems は 404 です。
• 1 日の平均（1 日あたり 1440 回＝「1 分に 1 回」）を、より短い文書化されていない 期間内に超えると、3 秒間隔を空けていても Marvin は 429 を返します。 2026-08-30 に 1 時間で約 100 回呼び出した後に確認されました。429 の後、 リミッターは 60 秒間（または Retry-After の指定時間）すべての呼び出しを 一時停止し、レスポンスヘッダーを記録します（許可リストにある名前のみ）。
• サーバーは書き込み時に検証を行いません（2026-08-29 に実環境でテスト済み）。 無効な日付、負数や範囲外の数値、型が間違った値、空のタイトル、無効な parentId/labelIds、未知のフィールドは、/doc/update（および /addTask 経由のほぼすべて）で文字列のまま保存されます。そのため、ツールは クライアント側で日付（厳密な YYYY-MM-DD、2000～2100 年）、タイトル、数値の範囲を 検証します。参照は検証されません（孤立するリスクについては説明に記載）。
• /doc/delete は、一度も存在しなかった ID やすでに削除された ID に対しても 200 を返します。冪等であり、404 は返しません（/doc/update とは異なります）。 一方、存在しない ID に対する /markDone は適切に 404 を、すでに完了している タスクに対しては 400 を返します。「存在しない」に対する応答が 3 つの エンドポイントでそれぞれ異なります（2026-08-29 に実環境でテスト済み）。
• 読み取りエンドポイント（/todayItems、/dueItems）は日付だけで絞り込まれます。 後回し設定、startDate、孤立状態（無効な parentId）は影響しません。また、 孤立した項目は unassigned にも表示されません（2026-08-29 に実環境でテスト済み）。 /todayItems?date=X は日付 X の項目だけでなく、day <= X の未完了項目をすべて返します （ロールオーバー有効時。2026-09-11 に実環境でテスト済み）。/markDone は 実行中の時間計測を停止し、現在は task.times も書き込みます （2026-09-02 に実環境でテスト済み。2026-08-29 時点では書き込まれませんでした。 サーバーの挙動が変更されています）。直接 /track STOP を実行しても times は書き込まれず、この場合は /tracks だけが記録として残ります。
• orbit/noAutoOrbit は Wiki のデータ型にはありませんが、実データには存在します （bool、2026-08-29 に確認済み）。更新ツールでは、文書化されていない パススルーパラメーターとして明示的に公開しています。
• プロジェクトとカテゴリーの変換はその場で行われます。_id、createdAt、 子項目は保持されます（2026-08-29 にアプリのフィールドテストと API の両方で確認済み）。 アプリには挙動が異なる 2 つの変換方法があります（2026-08-30/31 に確認済み）。 「設定を編集」ボタンでは day/dueDate/priority/isFrogged が恒久的に クリアされ、firstScheduled は残ります（Marvin のトラッカーのバグです）。 一方、右クリック／ホバーの方法では損失のない往復変換になります。ただし、 このボタンはデフォルトのメニューにはありません。右クリックメニューの歯車アイコン →「アクションを追加」から追加してください。 convert_category_or_project は 1.5.0 以降、デフォルトで情報を保持します。 クリーンなカテゴリーにするには clear_project_fields=True を渡してください （以前の値は removed_project_fields で返されます）。公式の変換エンドポイントは ありません。このツールは type を直接設定します。これは文書化されていない サーバーの挙動であり、実験的なものとして明記されています。
• /doc/create はサーバー生成の _id を返しません。後でドキュメントを参照する 必要がある場合は、自分で ID を指定してください。
• /doc/delete による削除は恒久的です。Marvin のゴミ箱はクライアント側の機能です。
• API 書き込み後のアプリの表示（2026-09-12 に実環境でテスト済み。PWA と Windows デスクトップアプリ 1.70.0 を同時に起動）：作成、フィールド変更、 カテゴリーと Inbox 間の移動は操作なしで即座に表示されます。 削除はまったく表示に反映されません。待っても、ビューを切り替えても解決しません。 Planning Ahead を有効にした状態での plannedWeek/plannedMonth のクリア （2026-08-29）と、戦略の切り替え（2026-08-29 以降のメソッドルール）でも 同じ現象が確認されています。対処手順： (1) 読み取り（親項目に対する get_children — タスクが表示されないこと）で サーバーの状態を確認します。(2) アプリに行がまだ表示される場合、それは アプリの表示の問題であってエラーではありません。アプリ内でその行を操作する 前にクライアントを再読み込みしてください。ウェブアプリ／PWA では F5、 デスクトップアプリでは再起動します（更新機能はありません）。 「操作する前」とする理由は、サーバー上ですでにドキュメントが削除されている行を アプリで編集すると、クライアントの競合解決によってドキュメントが再作成される 可能性があるためです（2026-09-12 に 2 つのクライアントのうち 1 つで一度確認。 どちらかは記録されていません。上流に報告済み）。これは Marvin クライアントの表示の問題です。反対方向（アプリ → MCP）に作用する get_done_items 独自の 30 分キャッシュとは混同しないでください。 ポイント＆クドス
• クドス（XP／レベル。/kudos で読み取ります）とリワードポイント （請求／請求取り消し／消費／リセット）は別々のシステムです。/kudos には nextMultiplier がありません（MarvinAPI の issue #5）。これは /me にあります。
• /markDone はタスクのリワードポイントを付与しません（クドスについては issue #6 を参照）。 claimRewardPoints は別途呼び出す必要があります。
• MANUAL の請求（itemId: "MANUAL"）は取り消せません。サーバーにはエントリーが保存されないため、/unclaimRewardPoints は 404 "No such entry" を返します（points フィールドの有無は問いません）。また、マイナスのポイントを請求すると 400 で拒否されます。Marvin の Web アプリは MANUAL を使用しません。これは API 専用の機能です。埋め合わせる唯一の方法は同額を消費することですが、その分、消費統計が水増しされます。
• 残高がマイナスになる場合、/spendRewardPoints は 500 を返します。
• アプリで購入できるリワードは、別の db="Rewards" ドキュメントに保存されており、公開 API からはまったくアクセスできません（2026-08-29 に実環境でテスト済み：/rewards とそのすべてのバリエーションが 404 を返し、リワードのプロファイルドキュメントはなく、/doc には特定できない ID が必要です）。Task フィールドの isReward はアプリのリワードフローとは連動しておらず、API 経由で設定しても UI に変化はありませんでした。

リマインダー

• Marvin のタスクリマインダーは、アプリだけが同期を保つ 2 つの書き込みで構成されます。タスクドキュメント内のリマインダーフィールド（taskTime、reminderTime、reminderOffset、snooze、autoSnooze）と、/reminder/set によるサーバー側のエントリーです。片方だけを書き込むと（API で簡単にできるのはこの方法だけです）、アプリ UI でタスクに表示されないエントリーや、サーバー側に孤立したエントリーが生じます。単独のリマインダー（タイプ M）は生の API を安全に使えるケースです。1.8.0 以降、ツールはアプリと同じ方法で両方を書き込みます。（このリスクは Recon2026/marvin-mcp によって初めて文書化され、 公式 wiki 自身の警告でも確認されています。）

時間と計画

• /todayTimeBlocks はブロックとカテゴリの関連付けを省略します（issue #65）。このサーバーは strategySettings.plannerSmartLists プロファイルドキュメントから対応関係を復元します。
• /track STOP を直接使って時間追跡を停止しても、タスク自体の times／duration フィールドは更新されません。正しい情報源は /tracks です。追跡中に /markDone を実行すると、times（2026-09-02 に実環境でテスト済み）と duration（2026-09-13 に確認済み）の両方が書き込まれます（Time Tracking がオンの場合、アプリでは追跡時間が「Completed Today」の下に表示されます）。
• /addEvent で作成したカレンダーイベントは、Marvin アプリがどこかで起動している間のみ同期されます（クライアント側のカレンダー同期）。 API で設定するフィールドの UI 動作（アプリで検証、2026-08-29）
• 戦略を切り替えた場合、そのフィールドが表示されるにはアプリの再起動が必要です。再起動しないと、新たに有効にした戦略のフィールドは表示されず、壊れているように見えます。
• backburner は、スケジュールされていないアイテムにのみ有効です。UI ではスケジュール（day）がこのフラグより優先されます。day: "unassigned" と backburner: true を一緒に設定してください。
• startDate は、開始日までは backburner アイテムを非表示にします（Start Dates 戦略の実際の動作です）。スケジュール済みのタスクは非表示にしません。
• アイコン名には、ライブラリ名の接頭辞（lucide-Rocket、huge-happy）または絵文字を指定します。プロジェクトのアイコンは、Master List → Configure View → "Show Custom Icon On" にプロジェクトが含まれている場合にのみ表示されます。"Categories & Projects"（2026-08-31 に検証）または "Just Projects"（2026-09-18 に検証）を選択してください。「プロジェクト自体のアイコンは表示されない」という以前の説明は、こちらのテストミスでした。
• プロジェクト独自の timeEstimate が優先されます。設定されていない場合、プロジェクトには子アイテムの見積もりの合計が表示されます（こちらからの報告に対する Marvin サポートの返信によるものです。以前の「集計されない」という結果は、プロジェクトと子アイテムの両方に見積もりを設定した、設計に不備のあるテストによるものでした）。
• スヌーズ中のタスク（itemSnoozeTime）はカテゴリビューでも非表示になります。ウィキの「マスターリスト以外のすべての場所」という説明は、カテゴリビューには当てはまりません。
• timeBlockSection はタスクを Today 内のタイムブロックのセクションに紐付けます。ただし、Time Block Sections 戦略が有効で、日表示がタイムブロックでグループ化されており（Group by → Group by time block section。デバイスごとの設定で、同期されません）、タスクがそのブロックの日にスケジュールされている場合に限ります。このフィールドを設定した未スケジュールのタスクは Today にまったく表示されません。ブロック自体にラベル／カテゴリのマッピングは不要です。このマッピング（Smart Time Block）は、別の独立した方法です。アプリで 2026-09-17 に検証（1.70.0.0、PWA ＋デスクトップ）。以前の「保存はされるが表示されない」という結果は、こちらのテストミス（グループ化を一度も設定していなかったため）であり、撤回します。Marvin サポートへの訂正連絡は保留中です。1.7.0 以降、create_time_block は time_block_id を返します（/doc/create はサーバー ID を返さないため、クライアント側で設定します）。この値は time_block_section に直接使用できます。
• reviewDate は Review ビューに表示されます。日表示のバナーには、さらに "Review Alert" ワークフロースニペットが必要です。
• 自動 Orbit が有効な場合、新たにスケジュールされたタスクは noAutoOrbit が設定されていない限り Orbit に追加されます。
• カテゴリに書き込まれたプロジェクト専用フィールド（day、dueDate、priority、isFrogged）は、サーバーでエラーなく受け入れられます（2026-09-11 にライブテスト）。update_category_or_project は構造上の理由から引き続き型チェックを行い、これらのフィールドをブロックします。カテゴリは完了することがないため、これらのフィールドはプロジェクトとタスクに属します。labelIds は異なります。カテゴリもプロジェクトと同じフィールドでラベルを持ち、API で設定したラベルは保存されて表示されます（2026-09-11 にライブテストとアプリでの検証済み）。そのため、1.6.0 以降、カテゴリでは label_ids が許可されています。

繰り返しタスクと発生分（2026-10-09 から 2026-10-11 にライブテスト）

• 発生分の ID は YYYY-MM-DD_<recurringTaskId> です。完了後 のタスクにチェックを付けて作成された発生分にはランダムな ID が付与され、API 経由で書き込まれるのは最初の 1 件だけです（echo: true、echoId: null）。次の発生分は /markDone の後、日付が echoDays 日後に設定されます。
• createAhead が未指定または null の場合、アカウントのデフォルト値が適用されます。アプリが custom ルールを正しく表示できるのは RRULE 文字列の場合だけなので、ツールは RRULE のみ受け付けます（「every other friday」のような文章でのルールは拒否されます）。
• アプリで Just this one を選んだ場合と同じ方法で発生分を 1 件削除すると、その ISO 日付が繰り返しタスクの deletedDates に追加されます。
• Only on weekdays が有効な場合、週末に当たる月の日付は金曜日に移動します。
• 発生分は、ラベル、優先度、サイズ、メモ、セクション、サブタスク（ID は <day>_<subid>）、および dueIn → dueDate を引き継ぎます。 ノートブック
• ノートブックを /doc/create で作成した後、GET /notebook?parentId= は 5 秒後と 12 秒後に 404「Notebook not found」を返しました。同じ時点で ?id= は 200 を返しました（原因不明）。その後、parent_id を指定した get_notebook は notebook_id を示唆するエラーを返します。
• プロジェクトの notePageId は、rank が最も低いページからサーバーが算出します。プロジェクトの note を書き込むと、そのページに書き込まれます。
• アプリでプロジェクトを削除しても（ノートも含めて）、サーバー上のノートブックとページは残ります。引き続き /notebooks と /notebook?parentId= に一覧表示されます。get_notebooks は、そのようなノートブックに parent_missing を付けます（完了済みのプロジェクトでは parent_done も付けます）。

リマインダーと時刻

• 時刻指定のタスクは、taskTime の「HH:MM」＋タスクの reminderTime（秒）などに加え、reminderId がタスクの ID であるタイプ T のサーバーエントリーで構成されます。独自のリマインダーは、タスクの reminders リストと、それぞれに対応するタイプ M のエントリーで構成されます。
• アプリでタスクを完了すると、サーバー上の T と M が削除されます。完了を取り消しても T は復元されませんが、M は引き続き通知します。リマインダーのあるタスクを削除する前に、サーバーエントリーも削除してください。削除しないと、開いているクライアントでリマインダーが鳴り続けます。

習慣

• undo を指定した /updateHabit は、常に最新の履歴エントリーを削除します。time も送信すると、さらに [time, 0] が追加されます。undo と一緒に time を送信しないでください。
• 数値目標を下回る記録では、習慣タスクに何も書き込まれません（habitRepAt は null のままです）。

プロジェクトの完了とその他のドキュメントの動作

• アプリでプロジェクトを完了すると、1 回のタイムスタンプ付き書き込みで done、doneAt = workedOnAt、day（未設定の場合は今日）、doneDate = day が書き込まれ、子タスクが未完了の間は完了できません。 mark_project_done も同じ動作をします。
• /categories は完了済みのプロジェクトを一覧表示しません。
• /markDone は workedOnAt を設定せず、fieldUpdates にタイムスタンプを付けません。day のないタスクでは、タイムスタンプを付けずに day を今日に設定します。
• 削除済みのドキュメントに対する GET /doc は {"error":"not_found","reason":"deleted"} を伴う 200 を返します。これに対して /doc/update は 500 を返します。
• /addTask は taskSize（XS–XL = 1–5）を破棄します。これは後から /doc/update で書き込まれます。

レート制限

• はじめにの説明には「3 秒ごとに 1 リクエストを超えるバーストは禁止」とあります。リミッターは作成系（/addTask、/addProject、/addEvent、/doc/create）の間隔を 1.1 秒、それ以外のすべての呼び出しの間隔を 3.1 秒にします。判定には、これから実行する呼び出しの種類が使われます。

既存の代替手段との違い

Amazing Marvin MCP サーバーには優れたものがいくつかあります。このサーバーはそれらを調査した後、コードを共有せずに一から構築しました。目標が異なり、厳選した一部ではなく、公開 API を完全にカバーすることを目指しています。

• bgheneti/Amazing-Marvin-MCP — 実績のある Python サーバーです。幅広くカバーしていますが完全ではなく、グローバルなレート制限はありません。
• Recon2026/marvin-mcp — 対象範囲はより小さい（ツール 19 個）ものの、調査はとりわけ丁寧です。書き込み 2 回のリスクを避けるため、リマインダーは読み取り専用にしています。このサーバーは代わりに、明示的な警告を付けてリマインダーの書き込みを提供します。
• lucasoeth/marvin-mcp — API のミラーではなく、少数の統合されたワークフローツール（brief／capture／…）を提供する、異なる方針のサーバーです。また、検索や完了済みタスクについて、公開 API ではまったくできない CouchDB の直接読み取りも行います。意見の反映されたワークフローや検索が必要ならこちらを、細かな注意点を文書化したうえで API に生のまま完全にアクセスしたいならこちらのサーバーをご利用ください。
• LucaDeLeo/amazing-marvin-mcp — 限定的な API の一部を提供します。

クレジットと出典

以下からコードをコピーしたわけではありません。ビルドは新たに行いましたが、これらはプロジェクトの形成に大きく影響しました。

• amazingmarvin/MarvinAPI （+wiki）— このサーバーの基盤となった公式 API ドキュメント、OpenAPI 仕様、データ型、課題トラッカーです。
• bgheneti/Amazing-Marvin-MCP — アーキテクチャの着想、初期のギャップ分析で参照したエンドポイント、MIT ライセンスを採用する先例です。
• Recon2026/marvin-mcp — リマインダーの二重書き込みによる整合性リスクへの気づきと、繰り返しタスクのインスタンスに関する基礎知識を得ました。どちらも検証し、ここに記載しています。
• lucasoeth/marvin-mcp — #Category ショートカットのバグ（ここで再現）と、Marvin の同期データベースが読み取りに利用できる実際の CouchDB であるという知見を得ました。
• LucaDeLeo/amazing-marvin-mcp — /addTask がサーバー側でショートカット構文を解析するという指摘（一部確認、一部否定。#Category の調査結果を参照）と、MCP ツールのアノテーションというアイデアを得ました。

Claude Code（Claude Fable 5、Fable 5.1、Opus 5.5）を使用して構築しました。

ライセンス

MIT。