# Zotero Research MCP

[![Test](https://github.com/tomozzz/Zotero-Research-MCP/actions/workflows/test.yml/badge.svg)](https://github.com/tomozzz/Zotero-Research-MCP/actions/workflows/test.yml)
[![Build Windows](https://github.com/tomozzz/Zotero-Research-MCP/actions/workflows/build-windows.yml/badge.svg)](https://github.com/tomozzz/Zotero-Research-MCP/actions/workflows/build-windows.yml)
[![Latest release](https://img.shields.io/github/v/release/tomozzz/Zotero-Research-MCP?display_name=tag)](https://github.com/tomozzz/Zotero-Research-MCP/releases/latest)
[![License: AGPL-3.0-or-later](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](LICENSE)

**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](https://github.com/tomozzz/Zotero-Research-MCP/releases/latest) ·
> [Installation](docs/installation.md) ·
> [ChatGPT setup](docs/chatgpt-setup.md) ·
> [Troubleshooting](docs/troubleshooting.md)

## 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 |
| --- | --- |
| ![Launcher status dashboard](docs/images/launcher.svg) | ![First-time setup wizard](docs/images/setup-wizard.svg) |

| Differential indexing | ChatGPT search example |
| --- | --- |
| ![Indexing progress](docs/images/index-progress.svg) | ![Illustrative ChatGPT search](docs/images/chatgpt-search-example.svg) |

![Illustrative answer with verified page references](docs/images/page-evidence-example.svg)

## 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](PRIVACY.md) and
[docs/privacy.md](docs/privacy.md).

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

## Architecture

```text
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](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](https://github.com/tomozzz/Zotero-Research-MCP/releases/latest).
   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](https://platform.openai.com/settings/organization/tunnels),
   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](https://github.com/openai/tunnel-client/releases/latest).
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](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)
and [developer-mode help](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt)
as the source of truth.

## 日本語クイックスタート

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

1. Zotero 7の **設定 → 詳細 → このコンピューター上の他のアプリケーションが
   Zoteroと通信することを許可** を有効にします。
2. [Releases](https://github.com/tomozzz/Zotero-Research-MCP/releases/latest)から
   インストーラーを取得し、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. チャットでアプリを選び、たとえば次のように依頼します。

```text
@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:

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

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

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

## CLI

```powershell
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

```powershell
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

```powershell
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](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](docs/installation.md)
- [ChatGPT and Secure MCP Tunnel setup](docs/chatgpt-setup.md)
- [Architecture](docs/architecture.md)
- [Privacy details](docs/privacy.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Security policy](SECURITY.md)
- [Contributing](CONTRIBUTING.md)
- [Third-party notices](THIRD_PARTY_NOTICES.md)

## License

The project source and combined binary are licensed under
[GNU AGPL-3.0-or-later](LICENSE). 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](THIRD_PARTY_NOTICES.md) and
[QT_SOURCE_OFFER.md](QT_SOURCE_OFFER.md).