Skip to main content
Glama
Readwise MCP Server

Readwise MCP Server

by IAmAlexander

Readwise MCP サーバー

Readwise ライブラリにアクセスして対話するための Model Context Protocol (MCP) サーバー。

特徴

  • Readwise ライブラリのハイライトにアクセス

  • 自然言語クエリを使用してハイライトを検索する

  • 図書館から本や文書を入手する

  • Claude やその他の MCP 対応アシスタントとのシームレスな統合

  • ハイライト分析のための強化されたプロンプト機能

  • トランスポートを考慮したログ記録システム

  • 堅牢なエラー処理と検証

  • 適切な request_id 処理による MCP プロトコル準拠

  • 監視用のヘルスチェックエンドポイント

  • APIキー検証を備えたセットアップウィザードの改善

Related MCP server: Readwise Reader MCP Server

プロジェクト構造

このリポジトリは、次の主要なディレクトリに編成されています。

  • src/ : Readwise MCP サーバーのメインソースコード

  • test-scripts/ : MCP サーバーの機能を検証するためのテスト スクリプトとユーティリティ

    • smart-mcp-test.sh : stdio と SSE トランスポートの両方のメインテストスクリプト

    • run-simple-server.sh : シンプルな MCP サーバーを実行するスクリプト

    • 完全なドキュメントについてはtest-scripts/README.mdを参照してください。

  • examples/ : 実装例とコードサンプル

    • examples/mcp-implementations/ : 基本的なMCPサーバーの実装

    • examples/test-clients/ : クライアント側テストスクリプト

    • 完全なドキュメントについてはexamples/README.mdを参照してください。

  • dist/ : コンパイルされたJavaScript出力(生成済み)

  • scripts/ : 開発とテストのためのユーティリティスクリプト

インストール

# Install from npm
npm install -g readwise-mcp

# Or clone the repository and install dependencies
git clone https://github.com/your-username/readwise-mcp.git
cd readwise-mcp
npm install
npm run build

設定

サーバーを使用する前に、Readwise API キーを設定する必要があります。

# Run the setup wizard
npm run setup

# Or start with the API key directly
readwise-mcp --api-key YOUR_API_KEY

API キーはhttps://readwise.io/access_tokenから取得できます。

使用法

コマンドライン

# Start with stdio transport (default, for Claude Desktop)
readwise-mcp

# Start with SSE transport (for web-based integrations)
readwise-mcp --transport sse --port 3000

# Enable debug logging
readwise-mcp --debug

API

import { ReadwiseMCPServer } from 'readwise-mcp';

const server = new ReadwiseMCPServer(
  'YOUR_API_KEY',
  3000, // port
  logger,
  'sse' // transport
);

await server.start();

MCP Inspectorによるテスト

このプロジェクトには、MCPインスペクターを使ったテストのための組み込みサポートが含まれています。インスペクターの実行には、TypeScriptスクリプトまたはシェルスクリプトを使用できます。

自動テスト

すべてのツールとプロンプトを検証する自動テスト スイートを実行します。

# Run automated inspector tests
npm run test-inspector

# Run in CI mode (exits with status code)
npm run test-inspector:ci

テスト スイートでは次の点を検証します。

  • サーバーの起動と接続

  • ツールの可用性と応答

  • プロンプト機能

  • エラー処理

  • 応答形式の準拠

各テストでは、詳細な出力と合格/不合格のケースの概要が提供されます。

手動テスト

シェルスクリプトの使用

# 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

# Full options
./scripts/inspector.sh --transport sse --port 3001 --debug

TypeScriptスクリプトの使用

# Test with stdio transport (default)
npm run inspector

# Test with SSE transport
npm run inspector -- -t sse -p 3001

# Enable debug mode
npm run inspector -- -d

# Full options
npm run inspector -- --transport sse --port 3001 --debug

利用可能なオプション

  • -t, --transport <type> : トランスポートタイプ (stdio または sse)、デフォルト: stdio

  • -p, --port <number> : SSEトランスポートのポート番号、デフォルト: 3001

  • -d, --debug : デバッグモードを有効にする

インスペクターコマンドの例

特定のツールをテストします。

./scripts/inspector.sh
> tool get-highlights --parameters '{"page": 1, "page_size": 10}'

プロンプトをテストします。

./scripts/inspector.sh
> prompt search-highlights --parameters '{"query": "python"}'

利用可能なツールとプロンプトを一覧表示します。

./scripts/inspector.sh
> list tools
> list prompts

Readwise APIキーなしでのテスト

Readwise API キーをお持ちでない場合、またはテストに実際の API キーを使用したくない場合は、模擬テスト機能を使用できます。

npm run test-mock

これは次のテスト スクリプトを実行します:

  1. Readwise APIのモック実装を作成します

  2. このモックAPIを使用してMCPサーバーをセットアップします

  3. サンプルデータを使用してさまざまなエンドポイントをテストします

  4. 実際のAPIキーを必要とせずにサーバーの機能を検証します

モック実装には以下が含まれます。

  • サンプルブック、ハイライト、ドキュメント

  • 現実的なテストのためのネットワーク遅延のシミュレーション

  • エラー処理テスト

利用可能なツール

  • get_highlights : Readwise ライブラリからハイライトを取得します

  • get_books : Readwise ライブラリから本を取得する

  • get_documents : Readwise ライブラリからドキュメントを取得する

  • search_highlights : Readwise ライブラリ内のハイライトを検索

利用可能なプロンプト

  • readwise_highlight : Readwise からのプロセスのハイライト

    • 要約、分析、関連性の発見、質問の生成をサポートします

    • 堅牢なエラー処理とパラメータ検証が含まれています

    • 読みやすい形式でハイライトをフォーマットします

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

    • ソース情報を含むフォーマットされた検索結果を提供します

    • ユーザーフレンドリーなメッセージでAPIエラーを適切に処理します

    • 必須パラメータの検証を含む

最近の改善点

強化されたMCPプロトコルコンプライアンス

  • すべてのレスポンスにおける request_id の適切な処理

  • MCPプロトコル仕様に対する受信リクエストの検証

  • MCPガイドラインに従った一貫したエラー応答形式

セットアップエクスペリエンスの改善

  • API キー検証を備えた対話型セットアップ ウィザード

  • 構成の安全な保管

  • トラブルシューティングのための詳細なエラーメッセージ

堅牢なエラー処理

  • さまざまな API エラー条件に対する特定のエラー メッセージ

  • すべてのツールとプロンプトで一貫したエラー形式

  • プロトコルに干渉しないトランスポート対応のログ記録

発達

# 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

ライセンス

マサチューセッツ工科大学

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables Claude to interact with the Readwise Reader API, allowing for saving, listing, updating, and deleting documents with complete metadata and content access through natural language.
      6
      47
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes Readwise and Reader operations as MCP tools, enabling AI agents to save URLs, search documents, retrieve full content and highlights, and manage tags and locations.
      MIT
    • F
      license
      A
      quality
      C
      maintenance
      Enables Claude clients to access a private local book library, allowing users to list books, search content, and retrieve metadata, chapter summaries, action items, personal notes, and infographic text through MCP tools.
      7
      -