Zoterobridge

🚀 ZoteroBridge

ZoteroBridgeは、ZoteroのSQLiteデータベースに直接接続することができるモデルコンテキストプロトコル（MCP）サーバーです。これにより、ClaudeやChatGPT、GitHub CopilotなどのAIアシスタントがZoteroの文献ライブラリとやり取りできるようになります。

🚀 クイックスタート

前提条件

• Node.js 18.0以上
• Zotero 7.0以上
• MCPをサポートするAIクライアント（Claude Desktop、Cursor、VS Code Copilotなど）

インストール方法

方法1：npmを使ったグローバルインストール（推奨）

npm install -g zotero-bridge

方法2：ソースコードからのビルド

# リポジトリをクローン
git clone https://github.com/Combjellyshen/ZoteroBridge.git
cd ZoteroBridge

# 依存関係をインストール
npm install

# プロジェクトをビルド
npm run build

AIクライアントの設定

Claude Desktop

Claude Desktopの設定ファイルに追加します。 Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "zotero-bridge": {
      "command": "npx",
      "args": ["-y", "zotero-bridge"],
      "env": {}
    }
  }
}

ソースコードからビルドした場合：

{
  "mcpServers": {
    "zotero-bridge": {
      "command": "node",
      "args": ["path/to/ZoteroBridge/dist/index.js"],
      "env": {}
    }
  }
}

Cursor IDE

プロジェクトのルートディレクトリに .cursor/mcp.json を作成します。

{
  "mcpServers": {
    "zotero-bridge": {
      "command": "npx",
      "args": ["-y", "zotero-bridge"]
    }
  }
}

VS Code Copilot

1. VS Codeの設定を開きます (Ctrl+,)
2. github.copilot.chat.mcpServers を検索します
3. "settings.jsonで編集" をクリックします
4. 以下の設定を追加します：

"github.copilot.chat.mcpServers": {
  "zotero-bridge": {
    "command": "npx",
    "args": ["-y", "zotero-bridge"]
  }
}

カスタムデータベースパス

Zoteroのデータベースがデフォルトの場所にない場合：

{
  "mcpServers": {
    "zotero-bridge": {
      "command": "npx",
      "args": ["-y", "zotero-bridge", "--db", "D:/MyZotero/zotero.sqlite"]
    }
  }
}

✨ 主な機能

• 🗂️ フォルダ管理 - Zoteroのフォルダ（コレクション）の作成、名前変更、移動、削除を行います。
• 🏷️ タグ管理 - 文献にタグを追加、削除、検索します。
• 📖 アイテム操作 - アイテムを検索し、詳細を取得し、フォルダとの関係を管理します。
• 📝 コンテンツ管理 - 要約を読み取り/設定し、ノートを追加します。
• 📄 PDF処理 - 全文を抽出し、要約を生成し、全文検索を行い、注釈を取得します。
• 🔍 識別子検索 - DOI、ISBN、PMID、arXiv、URLを使って文献を検索します。
• 🔗 関連アイテム - 手動で関連付けられた、またはタグ/著者を共有する類似文献を検索します。
• 🛠️ ライブラリメンテナンス - 重複アイテムを検索し、添付ファイルを検証し、孤立したレコードをクリーンアップし、アイテムをマージします。

📦 インストール

上述のクイックスタートセクションを参照してください。

💻 使用例

Claude/Copilotとの連携

# 文献を検索
タイトルに「ディープラーニング」が含まれるアイテムを検索

# 詳細を取得
itemIDが1234のアイテムの詳細情報を取得

# フォルダを管理
「機械学習論文」という名前の新しいフォルダを作成
アイテム1234をフォルダ5678に追加

# PDF操作
添付ファイルIDが100のPDFの全文を抽出
このPDF内で「neural network」を検索

# DOIで検索
DOIが10.1126/science.aaa2397の文献を検索

# 注釈を取得
アイテム1234のすべてのハイライト注釈を取得

# ライブラリメンテナンス
自分のライブラリ内の重複アイテムを検索
アイテム1234の添付ファイルが有効かどうかを確認

📚 詳細ドキュメント

利用可能なツール（13個のツール）

manage_collection - フォルダ管理

Zoteroのフォルダ（コレクション）のすべての操作を管理します。

manage_tags - タグ管理

タグのすべての操作を管理します。

search_items - アイテム検索

タイトルでZoteroのアイテムを検索します。

get_item_details - アイテム詳細取得

IDまたはキーを使ってアイテムの詳細情報を取得します。

manage_item_content - コンテンツ管理

アイテムの要約とノートを管理します。

manage_pdf - PDF操作

PDFファイルの様々な操作を行います。

find_by_identifier - 識別子検索

様々な識別子を使って文献を検索し、自動検出もサポートします。

get_annotations - 注釈取得

PDFの注釈（ハイライト、ノートなど）を取得し、タイプや色でのフィルタリングや検索もサポートします。

search_fulltext - 全文検索

Zoteroの全文インデックスで検索したり、添付ファイルの全文内容を取得したりします。

find_related_items - 関連アイテム検索

様々な方法で関連文献を検索します。

get_database_info - データベース情報

Zoteroのデータベース情報（パス、保存場所、統計データ）を取得します。

raw_query - 生SQLクエリ

生のSQLクエリを実行します（SELECTのみサポート、読み取り専用）。

library_maintenance - ライブラリメンテナンス 🆕

Zoteroライブラリのメンテナンスとクリーンアップを行うツールです。

🔧 技術詳細

プロジェクト構造

ZoteroBridge/
├── src/
│   ├── index.ts      # MCPサーバーのエントリーポイント
│   ├── database.ts   # Zotero SQLiteデータベースの操作
│   ├── pdf.ts        # PDF処理モジュール
│   └── tools.ts      # MCPツールの定義（13個の統合ツール）
├── dist/             # コンパイル出力
├── test/             # テストファイル
├── package.json
├── tsconfig.json
└── README.md

開発ガイド

開発モード

# ファイルの変更を監視し、自動的にコンパイル
npm run dev

ビルド

npm run build

コマンドライン引数

# ヘルプを表示
zotero-bridge --help

# データベースのパスを指定
zotero-bridge --db /path/to/zotero.sqlite

# 読み取り専用モード
zotero-bridge --readonly

📄 ライセンス

このプロジェクトは MITライセンス の下で公開されています。

🙏 謝辞

• Zotero - オープンソースの文献管理ツール
• Model Context Protocol - AIツールの統合プロトコル
• cookjohn/zotero-mcp - プロジェクトの参考

📬 連絡先

• 作者：Combjellyshen
• GitHub：https://github.com/Combjellyshen/ZoteroBridge
• npm：https://www.npmjs.com/package/zotero-bridge

IssueやPull Requestの提出を歓迎します！

更新履歴

v1.1.5 (2026-02-01)

🗑️ ゴミ箱識別機能

• ✅ すべてのクエリ関数が deletedItems テーブル内のアイテムを正しく除外するようになりました。
• ✅ getItemDetails に isDeleted と dateDeleted フィールドが追加されました。
• ✅ findItemByDOI/ISBN/Identifier が自動的にゴミ箱内のアイテムをスキップするようになりました。
• ✅ isItemDeleted() メソッドが追加され、アイテムがゴミ箱に入っているかを確認できるようになりました。
• ✅ getDeletedItems() メソッドが追加され、ゴミ箱の内容を取得できるようになりました。
• ✅ getDeletedItemsCount() メソッドが追加され、ゴミ箱内のアイテム数を取得できるようになりました。
• ✅ 添付ファイルのクエリも削除済みの添付ファイルを除外するようになりました。

v1.1.4 (2026-02-01)

🔧 重要な修正 - データベース互換性

• ✅ 重複アイテムのクエリ不一致の問題を修正 - findItemByDOI/ISBN が常に最新の修正されたアイテムを返すようになりました。
• ✅ itemTags.type フィールドを修正 - このフィールドは NOT NULL であり、値を提供する必要があります。
• ✅ note/attachment の itemTypeID を動的に取得するようになり、ハードコーディングされなくなりました。
• ✅ すべてのクエリが deletedItems テーブル内の削除済みアイテムを除外するようになりました。

🚀 新機能

• ✨ トランザクションサポートが追加されました (beginTransaction/commitTransaction/rollbackTransaction)。
• ✨ mergeItems がトランザクションを使用してデータの整合性を保証するようになりました。
• ✨ mergeItems に添付ファイルの転送機能が追加されました。
• ✨ 重複アイテムのクエリが _duplicateWarning 警告情報を返すようになりました。

🛡️ セキュリティの改善

• すべての書き込み操作の前にZoteroプロセスの状態を確認します。
• 自動的にデータベースのバックアップを作成します。
• バッチ操作はトランザクションで保護されます。

v1.1.3 (2026-02-01)

🔧 修正

• ✅ コレクション（フォルダ）の作成機能を修正 - 必須の clientDateModified フィールドを追加しました。
• ✅ コレクションの名前変更機能を修正 - clientDateModified タイムスタンプを正しく更新します。
• ✅ コレクションの移動機能を修正 - 親子関係が正しく確立されるようにしました。
• ✅ すべてのコレクション操作がZoteroの公式データベース規格に完全に準拠するようになりました。

以下の操作が正常に機能するようになりました：

• 新しいコレクション（トップレベルフォルダ）を作成
• 子コレクション（多層ネストをサポート）を作成
• コレクションの名前を変更
• コレクションを他の親コレクションに移動
• 子コレクションのリストを取得

v1.1.2 (2025-02-01)

• すべての依存関係を最新バージョンに更新しました。
• Zod 4.x の互換性問題を修正しました。
• pdf-parse 2.x ESM インポートの問題を修正しました。

v1.1.1 (2025-02-01)

• 42個のツールを13個のアクションベースのツールに統合しました。
• library_maintenance ツールを追加しました（重複検出、添付ファイルの検証、孤立データのクリーンアップ、アイテムのマージ）。

v1.1.0

• 初期統合バージョン

注意事項

⚠️ 重要な注意事項

• 書き込み機能を使用する場合は、Zoteroクライアントを閉じてデータベースのロックを避けてください。
• 変更を行う前に zotero.sqlite をバックアップしてください。
• データを読み取るだけの場合は、--readonly パラメータを使用するとより安全です。
• library_maintenance の validate_attachments を使用して、ファイルが存在するかを確認してください。