amazing-marvin-complete-mcp

Amazing Marvin 用の MCP（Model Context Protocol）サーバーで、公開 API を完全にカバーしています。全 ~31 のドキュメント化されたエンドポイントに対する 34 のツール、Marvin のドキュメント化された制限を尊重するグローバルレートリミッター、最小権限のトークンルーティング、MCP ツールアノテーションを備えています。ツールの説明にある明白でない動作の主張はすべてライブ API に対して検証済みです。その検証結果は下記の Marvin API の癖と検証結果 に記載されています。このサーバーを実行しなくても役立つ情報です。

現状のまま提供します。 このプロジェクトは積極的にメンテナンスされておらず、サポートもありません。Issue は意図的に無効化されています。MIT ライセンスなので自由にフォークしてください。

ツール（34）

意図的に含めていないもの: スマートリスト / タスク選択ロジック。タスクの選択は Marvin 自身の Spotlight が行います。このサーバーはアシスタントに「手」を与えるものであり、「意見」を与えるものではありません。

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

Related MCP server: Super-Productivity-MCP

Marvin トークンの取得方法

両方のトークンは Amazing Marvin の 設定 → API（app.amazingmarvin.com/pre?api）にあります:

• API トークン（MARVIN_API_TOKEN、必須）— 制限付きアクセス。タスクの読み取りと作成に十分です。

• フルアクセストークン（MARVIN_FULL_ACCESS_TOKEN、任意だが推奨）— すべての /doc* ベースのツールで必要: update_task、set_priority、unmark_done、delete_task、カテゴリ作成、タイムブロック、list_habits、リマインダー、reset_reward_points。

パスワードと同じように扱ってください。SECURITY.md を参照してください。

インストールと実行

Python 3.12+ が必要です。

git clone <this repo> && cd amazing-marvin-complete-mcp
python -m venv .venv && .venv/bin/pip install .

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

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

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "/path/to/.venv/bin/marvin-mcp",
      "env": {
        "MARVIN_API_TOKEN": "…",
        "MARVIN_FULL_ACCESS_TOKEN": "…",
        "MARVIN_TIMEZONE": "Europe/Stockholm"
      }
    }
  }
}

（Claude Code の場合: claude mcp add amazing-marvin -e MARVIN_API_TOKEN=… -- /path/to/.venv/bin/marvin-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 です。組み込みのベアラーチェック（MCP_AUTH_TOKEN）はすべてのパスを保護しますが、これは内部的なバリアであり、完全な認証ストーリーではありません。前面に TLS 付きのリバースプロキシを置き、Claude カスタムコネクタには OAuth 2.1 対応の MCP 認証プロキシを置いてください。HTTP モード用の Dockerfile が含まれています（非 root ユーザーで実行。/data にボリュームをマウントすると、日次レート制限カウンターを再起動後も保持できます）。

設定

すべての設定は環境変数を介して行います。完全な注釈付きリストは .env.example を参照してください。ハイライト: すべてのシークレットは *_FILE バリアントに対応しています（推奨）。MARVIN_TIMEZONE は Marvin アカウントが存在するタイムゾーンに合わせる必要があります（デフォルトはシステムタイムゾーン。ほとんどのコンテナでは UTC）。

レート制限

Marvin のドキュメント化された制限（書き込み 1 秒に 1 回、読み取り 3 秒に 1 回、1 日 1440 回）は、すべてのツールとセッションで共有される単一のプロセスグローバルキューによって強制され、マージン（1.1 秒 / 3.1 秒）が設定されています。日次カウンターは再起動後も保持され（STATE_DIR）、設定されたタイムゾーンの深夜にロールオーバーします。get_rate_limit_status で今日の使用状況を確認できます。

Marvin API の癖と検証結果

以下はすべて 2026-08-19 にライブ API に対して検証済みです。これはこのリポジトリのうち、実行しなくても使える半分です。

習慣

• 生データでない GET /habits は、習慣ドキュメントを読みません。これはサーバー側の追跡レジストリを読み取るもので、最初の記録時に遅延作成されます。一度も記録されたことのない習慣はレスポンスに完全に含まれず、エントリにはタイトルもありません（habitId + 履歴のみ）。実際の習慣ドキュメントを一覧表示するには ?raw=1（フルアクセストークン）を使用してください。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（スケジュール設定 — 期限ではありません）を設定します。どちらもタイトルからは削除されます。ただし、API 経由で #Category を使用しないでください: サーバーは文字列をリテラルに parentId として保存します（最初のハイフンまで貪欲に取得。例: #MCP-TEST → parentId: "#MCP" となりタイトルも壊れます）。ID の解決は行われません。タスクはすべてのカテゴリの外かつインボックスの外に存在することになり、実質的に見えなくなります。（lucasoeth/marvin-mcp が最初に報告。ここでも独立に再現済み。）

• 繰り返しタスクの生成インスタンスは決定的な ID（YYYY-MM-DD_<recurringTaskId>）を持つため、API 経由で完了/未完了をマークしても重複は発生しません。インスタンスは Marvin クライアントによって生成されるため、アプリが実行されるまで今日の繰り返しタスクが /todayItems に含まれないことがあります。

• /doc/update は散発的に一時的な 500 を返すことがあります。書き込みはアトミック（部分的な状態は発生しない）なので、単に再試行してください。プロジェクトの名前変更、移動、ラベル変更などはすべてこれで機能します。

• /doc/create はサーバー生成の _id をエコーバックしません。後でドキュメントを参照する必要がある場合は、自分で指定してください。

• /doc/delete による削除は永続的です。Marvin のゴミ箱はクライアント側の機能です。

報酬ポイントと kudos

• Kudos（XP/レベル、/kudos で読み取り）と報酬ポイント（claim/unclaim/spend/reset）は別々のシステムです。/kudos には nextMultiplier がありません（MarvinAPI issue #5）— これは /me にあります。

• /markDone はタスクの報酬ポイントを付与しません（kudos については issue #6 を参照）— claimRewardPoints は別の呼び出しです。

• MANUAL の claim（itemId: "MANUAL"）は取り消せません: サーバーはそのエントリを保存しないため、/unclaimRewardPoints は 404 "No such entry" を返します（points フィールドの有無にかかわらず）。また、負のポイントの claim は 400 で拒否されます。Marvin の Web アプリは MANUAL を決して使用しません — これは API 専用の機能です。唯一の補償手段は同額を spending することですが、これは spending 統計を水増しします。

• /spendRewardPoints は残高が負になる場合に 500 を返します。

リマインダー

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

時間と計画

• /todayTimeBlocks はブロック↔カテゴリのリンクを省略します（issue #65）。このサーバーは strategySettings.plannerSmartLists プロファイルドキュメントからマッピングを復元します。

• API 経由での時間追跡の停止は、タスク自身の times/duration フィールドを更新しません。/tracks が真実の情報源です。

• /addEvent で作成されたカレンダーイベントは、Marvin アプリがどこかで実行されている間のみ同期されます（クライアント側のカレンダー同期）。

既存の代替品との違い

優れた Amazing Marvin MCP サーバーはいくつか存在します。これはそれらを研究した後、新規に（共有コードなしで）構築され、異なる目標を持っています — 厳選されたサブセットではなく、公開 API の完全なカバレッジです:

• bgheneti/Amazing-Marvin-MCP — 確立された Python サーバー。広いが完全ではないカバレッジ、グローバルレート制限なし。

• Recon2026/marvin-mcp — より小規模（19 ツール）、異常に注意深い調査。2 回書き込みのリスクに対してリマインダーを読み取り専用にすることを選択。このサーバーは代わりに明示的な警告付きでリマインダー書き込みを提供します。

• lucasoeth/marvin-mcp — 異なる哲学: API ミラーではなく、少数の統合ワークフローツール（brief/capture/…）と、検索と完了タスクのための直接 CouchDB 読み取り（公開 API ではまったくできないこと）。意見のあるワークフローや検索が必要なら彼らのものを、文書化された鋭いエッジを持つ生の完全な API アクセスが必要ならこちらを使用してください。

• LucaDeLeo/amazing-marvin-mcp — Limited API のサブセット。

クレジットと情報源

これらからコードは一切コピーされていません — ビルドは新規です — しかし、これらはこのプロジェクトを実質的に形作りました:

• amazingmarvin/MarvinAPI（+ wiki）— このサーバーが基づいている公式 API ドキュメント、OpenAPI 仕様、データ型、Issue トラッカー。

• bgheneti/Amazing-Marvin-MCP — アーキテクチャのインスピレーション、初期ギャップ分析時のエンドポイント参照、MIT ライセンスの先例。

• Recon2026/marvin-mcp — リマインダーの 2 回書き込み整合性リスクと繰り返しタスクインスタンスに関する基礎研究。両方ともここで検証・文書化済み。

• lucasoeth/marvin-mcp — #Category ショートカットのバグ（ここで再現済み）と、Marvin の同期データベースが読み取りに使用できる実際の CouchDB であるという洞察。

• LucaDeLeo/amazing-marvin-mcp — /addTask がショートカット構文をサーバー側で解析するという指摘（一部確認、一部反駁 — #Category の検証結果を参照）、および MCP ツールアノテーションのアイデア。

Claude Code（Claude Fable 5）で構築。

ライセンス

MIT。