Readwise MCP Server

Readwise MCP サーバー

Readwise 向けの Model Context Protocol (MCP) サーバーです。AI アシスタントが、保存した記事、書籍、ハイライト、ドキュメントにアクセスできるようにします。

機能

• 書籍と記事：保存した書籍や記事のコレクションを閲覧できます
• ハイライト：ハイライトしたすべての箇所にアクセスできます
• 検索：Readwise ライブラリ全体からコンテンツを検索できます
• 最近のコンテンツ：最近保存した項目をすばやく取得できます
• タグ管理：タグを使ってコンテンツを整理、絞り込みできます
• 高度な検索：著者、日付、タグなどで強力に絞り込めます
• 読書の進捗：読書状況と完了率を追跡できます
• 一括操作：複数のドキュメントを一度に効率よく管理できます
• コンテンツ管理：ライブラリ内のコンテンツを保存、更新、削除できます
• 動画サポート：Readwise Reader に保存した動画にアクセスし、操作できます
• レート制限：API の制限を適切に処理し、スロットリングを防ぎます
• トランスポートオプション：stdio（Claude Desktop）と SSE（ウェブ）の両方のトランスポートに対応しています
• MCP 準拠：適切な request_id 処理を含め、プロトコルに完全準拠しています

インストール

Smithery 経由でのインストール

Smithery を使って Readwise MCP を Claude Desktop に自動インストールするには：

npx -y @smithery/cli install @iamalexander/readwise-mcp --client claude

手動インストール

1. Readwise API トークンを取得する：

   • Readwise アカウントにログインします
   • https://readwise.io/access_token にアクセスして、API トークンを生成します
   • 後で使用できるよう、トークンをコピーします

2. npm からインストールする：

   npm install -g readwise-mcp
   

3. または、クローンしてビルドする：

   git clone https://github.com/IAmAlexander/readwise-mcp.git
   cd readwise-mcp
   npm install
   npm run build
   

4. API キーを設定する：

   # Run the setup wizard
   npm run setup
   
   # Or start with the API key directly
   readwise-mcp --api-key YOUR_API_KEY
   

Docker サポート

Docker を使用する場合：

1. 設定ディレクトリを作成する：

   mkdir -p ~/.readwise-mcp
   

2. ビルドして実行する：

   docker build -t readwise-mcp .
   docker run -p 3001:3001 -e READWISE_API_KEY=your_key readwise-mcp
   

使用例

Claude に接続したら、次のような質問をして Readwise の知識を活用できます：

• 「『vibes-first programming』と美しい IDE に関するハイライトを探して」
• 「Claude Code の秘密のイースターエッグについて、何を保存した？」
• 「『AI』と『productivity』のタグが付いた記事をすべて表示して」
• 「まだ読み始めていない、読書リスト内の項目は何？」
• 「過去 3 か月に保存した、Paul Graham の記事を探して」
• 「読み終えた書籍を表示して」
• 「この記事を Readwise に保存して：https://example.com/interesting-article」
• 「量子コンピューティングに関するあの記事に、『must-read』タグを追加して」
• 「機械学習に関するあの書籍の読書の進捗は？」

動画関連の使用例

• 「Readwise に保存した YouTube 動画をすべて表示して」
• 「あの TypeScript に関する動画に、どんなハイライトを付けましたか？」
• 「あの AI カンファレンス動画の現在の再生位置はどこですか？」
• 「ライブラリから『machine learning』に言及している動画を探して」
• 「TypeScript チュートリアルの 23:45 に、『重要なパターン』というメモ付きのハイライトを作成して」
• 「あの AI 安全性に関する動画で、15 分あたりに登壇者は何と言っていましたか？」
• 「昨日保存したプログラミングチュートリアルの文字起こしを表示して」

機能ドキュメント

基本機能

コンテンツの閲覧

• 書籍と記事の一覧表示：ページネーションを使って、保存した書籍を取得します
• ハイライトの取得：フィルタリングオプションを使って、ハイライトした箇所をすべて確認します
• コンテンツの検索：ライブラリ全体を全文検索します
• 最近のコンテンツの取得：最近保存したアイテムにすばやくアクセスします

タグ管理

タグを使ってコンテンツを整理します。

• すべてのタグを一覧表示：ライブラリ内のすべてのタグを取得します
• ドキュメントのタグを取得：特定のドキュメントに付けられたタグを確認します
• タグを更新：ドキュメントのすべてのタグを置き換えます
• 特定のタグを追加：ドキュメントにタグを1つ追加します
• 特定のタグを削除：ドキュメントからタグを1つ削除します
• 一括タグ付け：複数のドキュメントに一度にタグを適用します

高度な検索

必要なものを正確に見つけるための強力なフィルタリングオプションです。

• query：検索テキスト
• category：コンテンツの種類（書籍、記事など）で絞り込みます
• tags：タグ（カンマ区切り）で絞り込みます
• author：著者で絞り込みます
• title：タイトルで絞り込みます
• location：場所（new、later、archive、feed）で絞り込みます
• dateFrom & dateTo：ISO 8601 形式の日付範囲
• sortBy：並べ替えに使うフィールド（created_at、updated_at、title、author）
• sortOrder：並べ替え順（asc、desc）

読書進捗の追跡

読書状況と進捗を追跡します。

• 読書進捗を取得：任意のドキュメントの現在の進捗を確認します
• 読書進捗を更新：ステータス、割合、ページ番号を設定します
• 読書リストを取得：読書状況で絞り込みます

読書状況：

• not_started：読み始めていません
• in_progress：読書中です
• completed：読み終えました

動画機能

Readwise Reader に保存した動画にアクセスして操作できます。

動画の一覧表示と詳細

• すべての動画を一覧表示：YouTube、Vimeo、その他のプラットフォームの動画を閲覧します
• 文字起こし付きで動画の詳細を取得：完全なメタデータと時刻同期された文字起こしにアクセスします

動画のハイライト

• タイムスタンプ付きのハイライトを作成：動画内の重要な場面に印を付けます
• 動画のハイライトを取得：動画のハイライトをすべて取得し、タイムスタンプ順に並べます

動画の再生位置

• 再生位置を更新：後で再開できるよう、現在の再生位置を保存します
• 再生位置を取得：前回中断したところから再開します

文字起こしへのアクセス方法

動画の文字起こし機能は、次のように動作します。

1. 動画の HTML コンテンツから、時刻同期された文字起こしを抽出します
2. タイムスタンプとテキストのペアを解析します
3. タイムスタンプ付きセグメントの配列として文字起こしを返します

これにより、次のことができます。

• 動画内の特定のコンテンツを検索する
• 正確な場面にハイライトを作成する
• 重要な箇所に直接移動する
• 正確な時間情報とともに動画の内容を参照する

コンテンツ管理

コンテンツを保存、更新、削除します。

• 新しいコンテンツを保存：URL、記事、カスタムコンテンツをライブラリに追加します
• ドキュメントを更新：タイトル、著者、概要、タグなどを変更します
• ドキュメントを削除：コンテンツを削除します（安全確認あり）

一括操作

複数のドキュメントを一度に効率よく管理します。

• 一括保存：複数の URL やコンテンツ項目を保存します
• 一括更新：複数のドキュメントを更新します
• 一括削除：複数のドキュメントを削除します
• 一括タグ付け：複数のドキュメントにタグを適用します

安全確認

誤ってデータを失わないよう、すべての一括操作と削除には明示的な確認が必要です。

• 単一ドキュメントの削除：確認パラメーターが必要です
• 一括操作：指定された確認文字列が必要です

これらの確認は、「human in the loop」の安全メカニズムとして機能します。

API ステータス

API のステータスとレート制限の情報はいつでも確認できます。

利用可能なツール

サーバーは、Readwise ライブラリを操作するための 30 個のツールを提供します。

コアツール

• get_highlights：フィルタリングとページネーションを使ってハイライトを取得します
• get_books：ライブラリから書籍を取得します
• get_documents：ライブラリからドキュメントを取得します
• search_highlights：クエリでハイライトを検索します
• get_tags：ライブラリ内のすべてのタグを一覧表示します
• get_recent_content：最近保存したコンテンツを取得します

タグ管理

• document_tags：ドキュメントのタグを取得、更新、追加、または削除します
• bulk_tags：複数のドキュメントにタグを適用します

読書の進捗

• get_reading_progress：特定のドキュメントの進捗を取得します
• update_reading_progress：読書ステータスと進捗を更新します
• get_reading_list：読書ステータスでフィルタリングしたドキュメントを取得します

ハイライト管理

• create_highlight：新しいハイライトを作成します
• update_highlight：既存のハイライトを変更します
• delete_highlight：ハイライトを削除します
• create_note：ハイライトにメモを追加します

検索ツール

• advanced_search：複数のパラメーターを使った強力な検索
• search_by_tag：タグでコンテンツを検索します
• search_by_date：日付範囲でコンテンツを検索します

動画ツール

• get_videos：ライブラリ内の動画を一覧表示します
• get_video：トランスクリプト付きで動画の詳細を取得します
• create_video_highlight：タイムスタンプ付きのハイライトを作成します
• get_video_highlights：動画のすべてのハイライトを取得します
• update_video_position：再生位置を保存します
• get_video_position：保存済みの再生位置を取得します

ドキュメント管理

• save_document：新しいコンテンツをライブラリに保存します
• update_document：ドキュメントのメタデータを変更します
• delete_document：ドキュメントを削除します

一括操作

• bulk_save_documents：複数のドキュメントを保存します
• bulk_update_documents：複数のドキュメントを更新します
• bulk_delete_documents：複数のドキュメントを削除します

利用可能なリソース

MCP リソースは、LLM クライアントに直接データへアクセスする手段を提供します。

• books（readwise://books）：Readwise ライブラリ内の書籍の一覧
• recent-highlights（readwise://highlights/recent）：ライブラリ内の最近のハイライト
• tags（readwise://tags）：Readwise ライブラリ内のすべてのタグの一覧

利用可能なプロンプト

• readwise_highlight：Readwise のハイライトを処理します

  • 要約、分析、関連性の発見、質問の生成に対応します
  • 堅牢なエラー処理とパラメーター検証を備えています
  • ハイライトを読みやすい形式で整えます

• readwise_search：Readwise のハイライトを検索して処理します

  • 出典情報付きで整形された検索結果を提供します
  • API エラーをユーザーにわかりやすいメッセージで適切に処理します
  • 必須パラメーターの検証を含みます

デモとテスト

このリポジトリには、機能のテストと確認に役立つデモファイルが含まれています。

デモファイル

• demo/test-connection.html：サーバーへの基本的な接続をテストします
• demo/mcp-demo.html：すべての機能を利用できる包括的な UI
• demo/video-features.html：動画機能に特化したインターフェース
• demo/enhanced-transcript-features.html：高度なトランスクリプト機能

テストの実行

# Run the full test suite
npm test

# Run automated inspector tests
npm run test-inspector

# Test without a real API key (mock mode)
npm run test-mock

MCP Inspector を使ったテスト

# Test with stdio transport (default)
./scripts/inspector.sh

# Test with SSE transport
./scripts/inspector.sh -t sse -p 3001

# Enable debug mode
./scripts/inspector.sh -d

統合

Claude Desktop

Claude Desktop の設定に追加します。

• Linux：~/.config/Claude/claude_desktop_config.json
• Mac：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "readwise": {
      "command": "readwise-mcp",
      "env": {
        "READWISE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

プロジェクト内の .cursor/mcp.json に追加します。

{
  "mcpServers": {
    "readwise": {
      "command": "readwise-mcp",
      "env": {
        "READWISE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code

CLI からインストールします。

claude mcp add readwise-mcp --transport http https://server.smithery.ai/@IAmAlexander/readwise-mcp/mcp

または、JSON 設定形式を使用します。

{
  "mcpServers": {
    "readwise-mcp": {
      "type": "http",
      "url": "https://server.smithery.ai/@IAmAlexander/readwise-mcp/mcp"
    }
  }
}

デプロイ

Smithery

Smithery CLI でインストールします：

npx @smithery/cli install @iamalexander/readwise-mcp --client claude

または、Smithery Registry で見つけてください。

Railway（ワンクリックデプロイ）

1. 上のボタンをクリックするか、Railway にアクセスします
2. GitHub リポジトリを接続します
3. 環境変数 READWISE_API_KEY を追加します
4. デプロイします！

Render

1. Render で新しい Web Service を作成します
2. GitHub リポジトリを接続します
3. Render が render.yaml を自動検出します
4. 環境変数 READWISE_API_KEY を追加します
5. デプロイします！

Docker

docker build -t readwise-mcp .
docker run -p 3001:3001 -e READWISE_API_KEY=your_key readwise-mcp

トラブルシューティング

トークンの問題

認証の問題が発生した場合：

1. https://readwise.io/access_token で Readwise API トークンがまだ有効か確認します
2. 保存された認証情報を削除して、認証をリセットします：

   rm ~/.readwise-mcp/credentials.json
   

3. 再起動して、もう一度接続を試します

接続の問題

サーバーに接続できない場合：

1. サーバーが実行中であることを確認します（手動で起動した場合）
2. ポート 3001 が他のアプリケーションに使用されていないことを確認します
3. AI クライアント（Claude Desktop、Cursor など）を再起動します

レート制限

サーバーにはレート制限が組み込まれています。レート制限エラーが発生した場合：

1. 数分待ってから、もう一度試します
2. リクエストの頻度を減らします
3. レスポンスのレート制限ヘッダーを確認します

動画固有の問題

1. 字幕が見つからない：すべての動画に字幕があるわけではありません。通常、YouTube 動画が最もよくサポートされています。
2. 字幕の品質：字幕は動画プラットフォームから取得されるため、誤りが含まれている場合があります。
3. タイムスタンプの不一致：プラットフォームによって形式が異なります。API は可能な場合に正規化します。
4. 再生位置が更新されない：position と duration の両方のパラメーターが指定されていることを確認します。

プライバシーとセキュリティ

• Readwise API トークンはローカルマシンに安全に保存されます
• Readwise データは、明示的にリクエストされた場合にのみアクセスされます
• MCP サーバーにデータが永続的に保存されることはありません
• 安全確認により、誤ってデータを失うことを防ぎます

開発

# Build the project
npm run build

# Run tests
npm test

# Start in development mode with auto-reload
npm run dev:watch

# Lint code
npm run lint

プロジェクト構成

• src/：メインのソースコード
• test-scripts/：テストスクリプトとユーティリティ
• examples/：実装例
• demo/：インタラクティブな HTML デモ
• tests/：テストスイート

コントリビューション

バグを見つけましたか？機能のアイデアがありますか？この MCP サーバーをさらに素晴らしいものにしたいですか？コントリビューションを歓迎し、奨励しています！

コントリビューション方法

1. このリポジトリをフォークします（お好みの飲み物を片手にどうぞ）
2. 機能ブランチを作成します（git checkout -b feature/my-amazing-idea）
3. ノリを大切にしたコードを書きます（RGB コメントも歓迎しますが、必須ではありません）
4. 変更をコミットします（git commit -m 'Add mind-blowing feature'）
5. ブランチにプッシュします（git push origin feature/my-amazing-idea）
6. プルリクエストを作成し、マージされたときの喜びを待ちます

規模の大小、実用的なものから遊び心のあるものまで、すべてのコントリビューションを歓迎します！

ライセンス

MIT License

Copyright (c) 2023 Alexander

本ソフトウェアおよび関連するドキュメントファイル（以下「ソフトウェア」）の複製を取得するすべての人に対し、ソフトウェアを制限なく取り扱うことを無償で許可します。これには、使用、複製、変更、結合、公開、配布、サブライセンス、および／または販売する権利、ならびにソフトウェアを提供する相手に同様の権利を許可する権利が含まれますが、これらに限定されません。ただし、以下の条件に従うものとします。

上記の著作権表示および本許諾表示は、ソフトウェアのすべての複製または実質的な部分に含めるものとします。

本ソフトウェアは「現状のまま」提供され、明示または黙示を問わず、商品性、特定目的への適合性、および権利非侵害の保証を含むがこれらに限定されない、いかなる保証もありません。いかなる場合も、作者または著作権者は、契約、不法行為、その他の行為に起因するかを問わず、本ソフトウェアまたはその使用、その他の取り扱いに起因または関連して発生した、いかなる請求、損害、その他の責任についても責任を負いません。