Raindrop.io MCP Server

Raindrop.io MCP サーバー

シンプルな MCP サーバーで、Raindrop.io を AI アシスタントに接続できます。自然言語を使ってブックマークを整理、検索、管理できます。

Raindrop.io では現在、Pro ユーザー向けにホスト型 Streamable HTTP MCP エンドポイント（https://api.raindrop.io/rest/v2/ai/mcp）もベータ版として提供しています。ホスト型のツールセットで十分な場合はそちらを使用し、ローカル stdio、セルフホスト可能な HTTP、および追加のライブラリ管理ツールを利用する場合はこのパッケージを使用してください。

できること

• コレクションとブックマークの作成、更新、削除
• タグ、ドメイン、種類、日付などでブックマークを検索
• タグの管理（一覧表示、名前変更、統合、削除）
• ブックマークのハイライトを読む
• コレクション内のブックマークを一括編集
• リンク切れや重複を監査し、ゴミ箱を管理

ツール

• diagnostics - サーバーの診断情報とライブラリの健全性指標
• collection_list - すべてのコレクションをフラットなリストで表示
• get_collection_tree - パンくずリストの完全なパスを含む、コレクションの階層表示
• collection_manage - コレクションの作成、更新、削除
• bookmark_search - フィルター、タグ、ページネーションを使った高度な検索
• bookmark_manage - ブックマークの作成、更新、削除
• get_raindrop - ID を指定して単一のブックマークを取得
• list_raindrops - ページネーションを使ってコレクションのブックマークを一覧表示
• get_suggestions - URL またはブックマークに対する AI を活用した整理のアドバイス（タグ／コレクション）
• suggest_tags - AI を活用した分析で、ブックマークのメタデータから関連性の高いタグを提案
• bulk_edit_raindrops - 特定のコレクション内のブックマークを一括更新、移動、削除
• tag_manage - タグの名前変更、統合、削除
• highlight_manage - ハイライトの作成、更新、削除
• library_audit - ライブラリ内のリンク切れ、重複、タグなしアイテムをスキャン
• empty_trash - ゴミ箱を完全に空にする（確認が必要）
• cleanup_collections - 空のコレクションを削除（確認が必要）
• remove_duplicates - 安全な確認フローで重複したブックマークを検出して削除

インストール

クイックスタート（一行コマンド）

ツール	一行コマンド
Gemini CLI	gemini extensions install https://github.com/adeze/raindrop-mcp
Codex CLI	codex mcp add raindrop -- npx -y @adeze/raindrop-mcp
Claude Code	claude mcp add raindrop -- npx -y @adeze/raindrop-mcp
GitHub Copilot	gh copilot config mcp add raindrop -- npx -y @adeze/raindrop-mcp
Vercel Skills	npx skills add adeze/raindrop-mcp

注: npx を使って MCP サーバーを追加するツールでは、シェルまたはツールの環境設定で環境変数 RAINDROP_ACCESS_TOKEN を設定する必要があります。

Vercel Skills（npx skills）

このプロジェクトは Vercel Skills システムに対応しています。必要なマニフェストはすべて含まれています。

• manifest.json: サーバー定義用の標準 MCP マニフェスト。
• SKILL.md: エージェントが認識するための標準化されたスキルの説明。
• mcp.json: MCP クライアントおよびレジストリ用のルート設定。

このサーバーをローカルのスキルディレクトリに追加するには：

npx skills add adeze/raindrop-mcp --global

これを Vercel Skills Registry に登録するには、このリポジトリの URL をレジストリに追加する Pull Request を送信してください。

Claude Desktop（MCPB）

GitHub のリリースから最新の raindrop-mcp.mcpb をダウンロードし、Claude Desktop に追加します。

• リリース：https://github.com/adeze/raindrop-mcp/releases

Claude Desktop でバンドルを追加し、次の環境変数を設定します。

• RAINDROP_ACCESS_TOKEN（Raindrop.io のインテグレーション設定から取得）

NPX（CLI）

API トークンを環境変数として設定し、次のコマンドを実行します。

export RAINDROP_ACCESS_TOKEN=YOUR_RAINDROP_ACCESS_TOKEN
npx @adeze/raindrop-mcp

MCP 設定の手動追加（mcp.json）

MCP クライアントの設定に次の内容を追加します。

{
  "servers": {
    "raindrop": {
      "type": "stdio",
      "command": "npx",
      "args": ["@adeze/raindrop-mcp@latest"],
      "env": {
        "RAINDROP_ACCESS_TOKEN": "YOUR_RAINDROP_ACCESS_TOKEN"
      }
    }
  }
}

HTTP

bun run start:http を実行すると、127.0.0.1:3002 で /mcp が提供されます。ポートを変更するには HTTP_PORT を設定します。HTTP ツールはサーバーの RAINDROP_ACCESS_TOKEN を使用します。ホストと Origin のチェックにより DNS リバインディングを防止しますが、呼び出し元の認証は行いません。リモートアクセスする場合は、ループバックエンドポイントの前に認証付きリバースプロキシを配置してください。

要件

• Raindrop.io アカウント
• Raindrop.io API アクセストークン：https://app.raindrop.io/settings/integrations

サポート

• 問題の報告：https://github.com/adeze/raindrop-mcp/issues

リリース

このリポジトリでサポートされているリリースフローは semantic-release のみです。

公開の仕組み

• 検証に合格すると、.github/workflows/publish.yml を介して master へのプッシュからリリースが実行されます。
• リリースの実行は直列化されます。リポジトリへの書き込み権限と OIDC 権限を持つのはリリースジョブのみです。
• semantic-release は Conventional Commit メッセージを分析し、次のバージョンを決定し、CHANGELOG.md を更新して GitHub でタグ付けとリリースを行い、npm に公開します。
• リリース準備中に、.releaserc.json が manifest.json、mcp.json、gemini-extension.json を同期し、その後 raindrop-mcp.mcpb をビルドして、GitHub リリースにバンドルが含まれるようにします。

リリース前のドライラン

• GitHub Actions で、master の Validate and Publish → Run workflow を選択します。リリースをプレビューするには dry_run を有効のままにし、semantic-release による公開を実行するには無効にします。
• これにより、公開せずにセマンティックバージョンの計算、レジストリ認証、リリースパイプラインの動作を検証できます。

必須シークレット

• GITHUB_TOKEN はリリースの自動化のために GitHub Actions から提供されます。

npm の信頼された公開

• npm への公開は、GitHub Actions の OIDC 信頼された公開を通じて設定されています。
• 手動のドライランも含め、信頼された発行元のワークフローファイル名は publish.yml に設定したままにしてください。
• 標準的な CI リリースフローでは NPM_TOKEN は不要です。

マージ前のローカル検証

Node 24.15+ と Bun 1.4.3+ を使用してください。公開済みのサーバーには Node 22.19+ が必要です。 Vite+ 1.1 は vite.config.ts を通じて、リント、フォーマット、型チェック、テスト、パッケージ化を管理します。 Bun は引き続きパッケージマネージャーとして使用します。

bun install --frozen-lockfile
bun run check
bun run test
bun run test:coverage
bun run docs

bun run build は vp pack を実行し、build/index.js、build/server.js、ソースマップ、バンドルされた依存関係を保持します。テストでは最初にビルドを実行するため、クリーンなチェックアウトからでもパッケージのチェックが機能します。bun run dev と bun run dev:http は Bun のサーバーのウォッチモードを引き続き使用します。bunx vp run dev でも同じスクリプトを実行できます。vp dev は Vite の Web サーバーを起動するもので、この MCP サーバーの開発用コマンドではありません。

サーバーでは TypeScript 7.0.2 を使用します。TypeDoc と OpenAPI 型生成には現在も TypeScript 6 のコンパイラー API が必要なため、tooling/compiler-api は独自の TypeScript 6.0.3 依存関係を保持しています。インストールはルートから行ってください。bun run docs では、引き続き既存のドキュメントが生成されます。

bun run update:deps は、カバレッジを Vite+ にバンドルされた Vitest 5.0.3 に合わせたまま、依存関係を更新します。Vite+ をアップグレードする際は、これらのバージョン指定もまとめて更新してください。同じ 61 件のテストが Vitest 5 の既定値で成功したため、移行時に生成された clearMocks: false の設定を削除しました。カバレッジの対象は Vitest 4 と同じ 16 ファイルで、しきい値や除外設定は緩和していません。元のビルドでは Bun を使用していたため、tsdown の互換性設定は不要でした。

未使用の Java/Axios ジェネレーターのスタックを削除しました。型付きの openapi-fetch は引き続き共有クライアントとして使用します。現在の OpenAPI ジェネレーターは、どちらも古い TypeScript コンパイラー API を必要とすることを確認しています。Hey API 0.99.0 は CLI のヘルプ表示前に TypeScript 7 で失敗します。分離してテスト済みのジェネレーターにより、認証、レート制限、キャッシュの動作への変更を回避できます。

リリースツールは引き続き braces 3.0.3 を取り込みます。このバージョンは GHSA-vfj7-8cjw-p6xm の影響を受けます。 修正済みバージョンは公開されていません。この依存関係はサーバーのバンドルには含まれません。信頼できない glob パターンをリリースツールに渡さないでください。

破壊的変更とレビュー済みの修正

• ブックマーク、コレクション、タグ、ハイライトの削除と一括削除には、confirm: true が必要になりました。クリーンアップツールの既存のプレビュー手順は維持されています。
• HTTP は 127.0.0.1 にバインドされます。OAuth コールバックには、一致し、有効期限内で、一度だけ使用できるブラウザー状態が必要です。リモートアクセスには認証済みプロキシが必要です。
• 一括移動／更新／削除には、ソースコレクションの API エンドポイントを使用します。ブックマークの更新では collectionId が保持されます。他のフィールドのみを変更する場合は、URL とタイトルを省略してください。コレクション 0 はすべてを意味し、一括変更には使用できません。-1 は未分類を意味します。
• タグでは上流の検索演算子を使用し、ページネーションと合計件数を保持します。コレクションのパスは API の並び順に依存しなくなりました。変更時には、影響を受けるブックマーク、検索、コレクション件数のキャッシュが無効化されます。
• 恒久的な上流エラーは再試行されません。リソーステンプレートでは MCP SDK を使用します。サポートされていないリソースサブスクリプションは、提供されているものとして通知されなくなりました。
• MCPB パッケージには、開発用依存関係ではなく、バンドル済みのランタイムコードが含まれます。環境ファイル、ログ、ローカルの Codex 状態は除外されます。

これらの修正は、PR #52 と issues #54/#55 の主な内容に対応しています。 以前の SDK v1／Zod 3 への移行は、この SDK v2 の構成によって置き換えられました。既存の SDK API と共有サービスヘルパーによって冗長なコードが不要になったため、フレームワークの置き換えは不要でした。実際の Raindrop の変更と OAuth プロバイダーへのログインは、引き続き手動で検証する必要があります。

コミットメッセージの例

• fix: handle empty tag merge payload
• feat: add collection path filter
• feat!: remove deprecated search parameter

通常のリリースでは、バージョンを手動で更新したり、リリースタグをプッシュしたり、npm の公開コマンドを手動で実行したりしないでください。

📋 最近の機能強化（v2.4.x）

スマートな整理と階層構造

• AI による提案：新しい get_suggestions ツールは、Raindrop の API と MCP Sampling を使用して整理に関するアドバイスを提供します。
• コレクションツリー：get_collection_tree ツールは、パンくずリスト形式の完全なパスを含む階層ビューを提供します。
• 一括移動：ライブラリを効率的に整理できるよう、bulk_edit_raindrops に move 操作を追加しました。
• ページネーションのサポート：大規模なライブラリに対応するため、list_raindrops と bookmark_search にページネーションを導入しました。

安全性と品質

• 確認ロジック：破壊的な操作を行うツール（empty_trash、cleanup_collections）で、明示的な確認が必要になりました。
• 命名規則の統一：すべてのツールで一貫した snake_case の命名規則を使用するようになりました。
• CI/CD パイプライン：自動リンティング、型チェック、トランスポートを横断したテストを行うよう、GitHub Actions を強化しました。
• コード品質：保守しやすい開発を実現するため、ESLint と Prettier の設定を整備しました。

📋 以前の機能強化（v2.3.3）

高度なクリーンアップとライブラリの監査

📋 以前の機能強化（v2.3.2）

MCP リソースリンクの実装

• 現在の MCP SDK のベストプラクティスに沿った最新の resource コンテンツ
• 効率的なデータアクセス：ツールは完全なペイロードではなく、軽量なリンクを返します
• パフォーマンスの向上：クライアントは必要な場合にのみ、ブックマーク／コレクションの全データを取得します
• 動的リソースシステム（mcp://raindrop/{id}）とのシームレスな統合

SDK と API の更新

• このリポジトリでサポートされている最新の MCP SDK に更新しました
• 説明を改善した最新のツール登録方式を導入しました
• API エンドポイントとパスパラメーターを修正しました
• すべてのコアツールが完全に機能します

ツールの最適化

• ブックマーク／コレクションの一覧における、リソース効率の高いレスポンス
• mcp://collection/{id} と mcp://raindrop/{id} を介した動的なリソースアクセス
• 一覧のペイロードを軽量化し、クライアントの UX を改善
• 公式 SDK のパターンに完全準拠した MCP 実装

サービスレイヤーの改善

• 共通ヘルパーの抽出によりコードを削減
• エラー処理とレスポンス処理を統一
• 汎用ハンドラーによって型安全性を強化
• エンドポイントの構築を一元化

テストの改善

• MCP ツールの実行に関するエンドツーエンドテストの網羅性を向上
• 実際のクライアントの利用フローを対象とした統合テストを拡充

MCP 2.0 への準備（一括操作）

• MCP 2.0 の一括操作ワークフローとツールの基盤を整備

OAuth（近日公開）

• 手動でトークンを設定せずにセットアップできる、OAuth ベースの認証フロー

注記

直近の数回のビルドで影響を受けた皆様にお詫び申し上げます。お待ちいただき、問題を報告してくださったことに感謝いたします。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については LICENSE ファイルをご覧ください。