amazing-marvin-mcp

概要

Amazing Marvin 用の非公式 MCP サーバーです。Claude などのアシスタントが「受信トレイには何がある？」「今週の締め切りは？」「車の中だけど、何ができる？」といった質問に答え、それに基づいて行動できます。タスクの名前変更、ラベル付け、スケジュール変更、移動、プロジェクトへの分割、調査結果のメモへの保存などが可能です。

このプロジェクトは Amazing Marvin とは提携、承認、サポートされておらず、同社の公開APIを使用しています。

仕組み

Claude ──MCP (stdio)──▶ amazing-marvin-mcp
                          ├─ local mirror ◀── CouchDB `_changes` (your sync database)
                          │    reads, search and filters run here: no rate-limit cost
                          └─ writes ──▶ Marvin REST API (addTask, doc/update, markDone)
                                        throttled to Marvin's limits (1 request / 3 s)

Marvin の REST API には「一覧」や「検索」エンドポイントがなく、1日あたり1440リクエストという予算があるため、読み取りはローカルにコピーしたデータベースから行います。このコピーは、増分 _changes ポーリング（最大でも1分に1回）で最新の状態に保たれます。書き込みは REST API を通じて行われ、Marvin の競合解決ブックキーピング（fieldUpdates）はサーバー側で処理されます。

アシスタントが把握していること

• Marvin のセマンティクス（UI の用語で表現）。受信トレイ = どこにもファイリングされていないもの。カテゴリとプロジェクトは任意にネストできます（マスターリスト）。4つの日付は区別されます。実行日（実行予定日、「スケジュール済み」）、期限日（厳格な外部締め切り）、終了日（自己設定の目標。Planning Ahead の計画週/月はより緩やかな形式）、開始日（それまで Backburner に非表示）。さらに、所要時間の見積もり（分）、重要度（P1〜P3 の星）、Eat-the-Frog、Backburner、ラベルとラベルグループも含まれます。

• あなたの構造（get_structure）：ID と未完了タスク数を含むカテゴリ/プロジェクトツリー、グループごとのラベル、有効にしている Marvin の戦略（Strategies 画面での名前で表示）。

• あなたのワークフロー（workflow.md または workflow/ ディレクトリ内のセクション群）：あなたが Marvin をどのように使っているか。ラベルの意味、計画の立て方、受信トレイのトリアージチェックリスト、「ショートウィン」の意味など。Marvin は柔軟性が高いため、これによりアシスタントがあなたと同じように行動できるようになります。これはサーバー指示に注入され、marvin://workflow（および marvin://workflow/<section>）として公開されます。

ツール

削除ツールは意図的にありません。Marvin のゴミ箱はクライアント側にあるため、API による削除は復元できません。

Related MCP server: Amazing Marvin MCP

インストールとセットアップ（使用する場合）

1. インストール（uv が必要です）:

   uv tool install git+https://github.com/tsvikas/amazing-marvin-mcp.git

2. 認証情報。 Marvin で API 戦略を有効にします（Strategies → API → 設定）。その値を ~/.config/amazing-marvin-mcp/.env に設定します（Linux の場合。amazing-marvin-mcp check でお使いの OS での正確なパスが表示されます）:

   MARVIN_API_TOKEN=...           # create / mark done
   MARVIN_FULL_ACCESS_TOKEN=...   # edit existing items; omit for no edits
   MARVIN_SYNC_SERVER=...         # CouchDB: the read mirror
   MARVIN_SYNC_DATABASE=...
   MARVIN_SYNC_USER=...
   MARVIN_SYNC_PASSWORD=...

   環境変数と作業ディレクトリ内の .env も機能します（ユーザーごとのファイルを上書きします）。試している間は、使い捨ての2つ目の Marvin アカウントを使用してください。フルアクセストークンはデータを破損させる可能性があります。

3. チェックと最初の同期:

   amazing-marvin-mcp check     # verifies tokens, pulls the database, prints counts

4. ワークフローの説明:

   amazing-marvin-mcp init-workflow            # one workflow.md to edit, or
   amazing-marvin-mcp init-workflow --split    # a workflow/ directory: planning, labels, triage, daily…

   その内容はすべてモデルの指示に含まれます（各セクションは marvin://workflow/<section> リソースにもなります）。簡潔かつ具体的にしてください。

5. MCP クライアントに登録します。

   Claude Code:

   claude mcp add marvin -- amazing-marvin-mcp serve

   Claude Desktop（claude_desktop_config.json）:

   {
     "mcpServers": {
       "marvin": { "command": "amazing-marvin-mcp", "args": ["serve"] }
     }
   }

   どちらもユーザーごとの .env を読み取るため、クライアント設定にシークレットは含まれません。その後、「Marvin の受信トレイには何がある？」と尋ねてください。

その他の設定（check で表示）: MARVIN_WORKFLOW_FILE（ファイルまたはディレクトリ）、MARVIN_CACHE_DIR、 MARVIN_MIN_REQUEST_INTERVAL（REST 呼び出し間の秒数、デフォルトは 3）、 MARVIN_MIRROR_MAX_AGE（読み取りが再ポーリングするまでの秒数、デフォルトは 60）。

ミラーファイルにはすべてのタスクが含まれており、キャッシュディレクトリの下に所有者のみがアクセスできる権限で書き込まれます。

開発

git clone https://github.com/tsvikas/amazing-marvin-mcp && cd amazing-marvin-mcp
uv sync && just prepare                     # deps + pre-commit hooks
just test && just lint

チェックアウトからサーバーを実行します（リポジトリルートの .env は git で無視され、クライアントがこのディレクトリから起動した場合に読み取られます。それ以外の場合は -e VAR=value またはユーザーごとのファイルを使用します）:

claude mcp add marvin-dev -- uv run --directory "$PWD" amazing-marvin-mcp serve

tests/test_live.py はすべてのツールをエンドツーエンドで実行し、デフォルトでは記録されたカセット（tests/cassettes/）を再生します。これは実際の Marvin ドキュメントのフィクスチャも兼ねています。使い捨てアカウントに対して再録音するには（いくつかの [live] アイテムを作成してから削除します）:

MARVIN_API_TOKEN=... MARVIN_FULL_ACCESS_TOKEN=... MARVIN_SYNC_SERVER=... \
MARVIN_SYNC_DATABASE=... MARVIN_SYNC_USER=... MARVIN_SYNC_PASSWORD=... \
uv run pytest tests/test_live.py --record-mode=rewrite

貢献に関する設計ルールは CLAUDE.md にあります。

貢献

貢献に興味がありますか？ 開発環境のセットアップとガイドラインについては CONTRIBUTING.md を参照してください。