Zotero Research MCP

Search and discuss papers in your own Zotero library from ChatGPT, with exact page evidence and a read-only local index.

Zotero Research MCP is a Windows-first desktop application. It reads metadata and PDF paths through Zotero Desktop's Local API, extracts text page by page, indexes it locally with SQLite FTS5, and exposes bounded research tools through OpenAI Secure MCP Tunnel. It never writes to Zotero and never sends an entire PDF by default.

日本語クイックスタート · Download · Installation · ChatGPT setup · Troubleshooting

Why this project

ChatGPT cannot directly read a private Zotero library on a local PC. This project provides a narrow bridge designed for research work:

• metadata and full-text search across a local Zotero library;
• search limited to one identified paper;
• exact page retrieval for evidence checking;
• comparison by author, year, collection, tag, and section;
• bibliography and BibTeX retrieval;
• English scientific-term searches for Japanese questions; and
• a visible Windows launcher for Zotero, MCP, tunnel, and index status.

Every user runs their own copy against their own Zotero library, creates their own OpenAI tunnel, and connects it to their own ChatGPT account/workspace. The maintainer cannot see other users' libraries or chats, and other users do not consume the maintainer's ChatGPT message quota or API credits.

Screenshots

All screenshots contain synthetic data; no personal library content is included.

Launcher	First-time setup

Differential indexing	ChatGPT search example

What is included

The MCP server exposes eight read-only tools:

Tool	Purpose
search	Find relevant passage candidates across the indexed library
fetch	Retrieve one paper, chunk, or page by MCP ID
search_papers	Search papers with metadata and library filters
search_within_paper	Search only inside one identified paper
list_collections	List available Zotero collections
get_bibliography	Return formatted bibliography or BibTeX-compatible data
get_index_status	Report local index readiness and progress
get_page	Retrieve one bounded, numbered PDF page

Search results include a non-empty URL and IDs that can be passed to fetch. Retrieved evidence contains paper title, year, section, page number, DOI/Zotero identifiers, and bounded text. A missing passage is reported as missing instead of being guessed.

Safety and privacy model

Boundary	Enforced behavior
Zotero	Local API only at http://127.0.0.1:23119/api/
HTTP methods	Only GET and HEAD; write methods are rejected in the client layer
Zotero database	zotero.sqlite is never opened directly
MCP server	Loopback only; default http://127.0.0.1:8765/mcp
Remote connection	Outbound OpenAI Secure MCP Tunnel; no inbound port forwarding
PDFs	Read in place from Zotero-returned paths; no library PDF is bundled or uploaded
ChatGPT payload	Relevant bounded passages, not unconditional whole-document dumps
Secrets	Tunnel runtime key in the OS keyring; never settings, logs, or command arguments
PDF content	Treated as untrusted evidence, never executable instructions
Telemetry	No project telemetry or automatic crash upload

The local SQLite index contains extracted paper text and is sensitive. When ChatGPT is used, the query, selected passage, bibliography, and page metadata are processed through the user's OpenAI account. See PRIVACY.md and docs/privacy.md.

Do not expose ports 23119 or 8765 to a LAN or the internet.

Architecture

ChatGPT
   │  OpenAI Secure MCP Tunnel (outbound HTTPS)
   ▼
official openai/tunnel-client       separately installed by the user
   │  http://127.0.0.1:8765/mcp
   ▼
Zotero Research MCP
   ├─ read-only MCP tools
   ├─ SQLite + FTS5 index           local application data
   └─ PyMuPDF page extraction       original PDF read in place
          ▲
          │ file URL/path supplied by Zotero Local API
Zotero Desktop
   └─ http://127.0.0.1:23119/api/   GET/HEAD only

See docs/architecture.md for components, trust boundaries, sync transactions, and the index lifecycle.

Requirements

• Windows 10 version 1809 (build 17763) or later, or Windows 11;
• Zotero 7 or later with the Local API enabled;
• a ChatGPT plan/workspace with developer-mode custom-app access;
• an OpenAI Platform organization and tunnel with the required permissions;
• the official OpenAI tunnel-client, downloaded separately; and
• outbound HTTPS while using the ChatGPT connection.

Python 3.12 is required only for source/developer installation. Windows release builds contain their Python runtime. ChatGPT availability, developer-mode controls, and tunnel permissions depend on the user's current OpenAI plan and workspace policy.

Five-minute Windows setup

1. Install Zotero 7 and enable Settings → Advanced → Allow other applications on this computer to communicate with Zotero.
2. Download the installer or portable ZIP from GitHub Releases. Verify the file against SHA256SUMS.txt.
3. Start Zotero Research MCP, complete the wizard, and choose which Zotero collections to index.
4. In OpenAI Platform tunnel settings, create a tunnel and associate it with the intended Platform organization and ChatGPT workspace. The operator needs Tunnels Read + Use; creating or editing the tunnel needs Tunnels Read + Manage.
5. Download the official tunnel-client using the link in OpenAI Platform or the official latest release.
6. In the launcher, select tunnel-client.exe, enter the Tunnel ID, organization ID when required, and a restricted runtime key. The key is stored in Windows Credential Manager.
7. Choose Initialize tunnel, Start all, and Test connection. Wait until the index is Ready and the tunnel is Connected.
8. In ChatGPT web, enable developer mode for your account/workspace. Open Settings → Apps → Create (or Settings → Plugins → + where that UI is still shown), choose Tunnel, select the tunnel, scan the tools, and create the app.
9. Open a new chat, select the draft/custom app from the tools menu, and test search followed by fetch.

OpenAI product labels change over time. Use the current Secure MCP Tunnel guide and developer-mode help as the source of truth.

日本語クイックスタート

このアプリは、各利用者のPCにあるZoteroライブラリを読み取り専用で検索し、 必要な本文だけをページ番号付きでChatGPTへ渡します。開発者や他の利用者に ライブラリ全体が共有される仕組みではありません。

1. Zotero 7の 設定 → 詳細 → このコンピューター上の他のアプリケーションが Zoteroと通信することを許可 を有効にします。
2. Releasesから インストーラーを取得し、SHA-256を確認して導入します。
3. 初回ウィザードで検索対象コレクションを選び、最初の索引を作成します。
4. OpenAI Platformで自分用のTunnelを作成し、公式 tunnel-client、Tunnel ID、 必要に応じてOrganization ID、制限付きランタイムキーを設定します。
5. Initialize tunnel → Start all → Test connection の順に実行します。
6. ChatGPT Webの開発者モードからカスタムアプリを作成し、Connectionで Tunnelを選びます。
7. チャットでアプリを選び、たとえば次のように依頼します。

@Zotero Research MCP
出血性ショック時の微小循環と乳酸の関係を調べた論文を探して。
英語の科学用語でも検索し、根拠本文を取得したページ番号を示して。

利用者は自分のChatGPTアカウントとOpenAI Platform設定を使います。他の人が このソフトを使っても、リポジトリ所有者のチャット回数やAPIクレジットは消費されません。

Everyday use

After setup, open Zotero Research MCP from the Start menu. With automatic startup enabled, the launcher waits for Zotero, starts the local MCP service, starts the external tunnel client, and performs a differential sync. Closing the window normally leaves the app in the notification area; use Exit to stop its MCP and tunnel child processes.

Example requests:

Find animal studies that experimentally validated endothelial, neurogenic,
and myogenic flowmotion bands. Exclude papers that only cite human bands.

Search within this paper for statements about anesthesia affecting blood-flow
oscillations. Separate reported results from author interpretation and give pages.

Compare these five papers by species, device, sampling rate, spectral method,
main result, and limitation. Fetch the supporting passages before answering.

CLI

zotero-research-mcp doctor
zotero-research-mcp start
zotero-research-mcp stop
zotero-research-mcp status
zotero-research-mcp sync
zotero-research-mcp reindex
zotero-research-mcp collections
zotero-research-mcp logs

The local health endpoint is http://127.0.0.1:8765/healthz. Run zotero-research-mcp --help for the installed version's exact options.

Install from source

git clone https://github.com/tomozzz/Zotero-Research-MCP.git
cd Zotero-Research-MCP
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
zotero-research-mcp doctor

Never use a real paper PDF, Zotero database, or extracted index as a public test fixture.

Development and validation

ruff check .
mypy src
pytest
python -m build
pyinstaller --noconfirm --clean packaging\pyinstaller\ZoteroResearchMCP.spec

Tagged releases are built by GitHub Actions. They include a portable Windows archive, per-user installer, Python wheel, source distribution, and SHA256SUMS.txt. The workflow also verifies the frozen runtime, legal bundle, local-only boundaries, silent install/uninstall, console self-test, PDF parser, and MCP HTTP startup.

See CONTRIBUTING.md before proposing changes. Changes that add a Zotero write path, expose local ports, bundle credentials, or include private research data will not be accepted.

Known limitations

• Zotero Desktop must be running for metadata refresh and attachment path resolution.
• The official tunnel client must remain running while ChatGPT calls the app.
• Image-only PDFs are marked PDF_OCR_REQUIRED; OCR execution is not implemented in version 0.1.
• Figures, image-only tables, handwriting, and semantic/vector search are not analyzed.
• Unavailable linked/WebDAV files remain metadata-only.
• Windows release binaries are unsigned until a code-signing process is established.
• ChatGPT app registration remains manual and account/workspace dependent.
• macOS/Linux CLI use is best effort; the supported GUI/installer path is Windows.

Documentation

• Installation
• ChatGPT and Secure MCP Tunnel setup
• Architecture
• Privacy details
• Troubleshooting
• Security policy
• Contributing
• Third-party notices

License

The project source and combined binary are licensed under GNU AGPL-3.0-or-later. PyMuPDF is used under its open-source licensing route. PySide6/Qt libraries are distributed under LGPLv3 with the notices and corresponding-source offer in THIRD_PARTY_NOTICES.md and QT_SOURCE_OFFER.md.