OpenRef
JA Install
OpenRef Icon

Collect, Read, and Cite.
With AI, Right on Your Mac.

Capture papers from your browser in one click. Metadata is resolved authoritatively via PubMed and Crossref, PDFs stay on your disk, Word citations format automatically, and Claude (MCP) works directly with your local SQLite library.

Install GitHub (MIT)

macOS 14+(Apple Silicon) · Free forever · Open source (MIT) · No telemetry · No account required

OpenRef with a real library: folders and labels on the left, the paper list in the middle (143 items, one selected), and the selected paper's details and abstract on the right; the tab bar shows the list and an open PDF
A real library open in OpenRef: folders and labels on the left, the paper list in the middle, the selected paper's details and abstract on the right; PDFs open in tabs. Paste a PMID or DOI into the add box (⌘N) to add a paper.
Components

Four tools connected by a single local SQLite library

Desktop app, Chrome extension, Word add-in, and MCP server — all reading and writing the same local database on your Mac.

APP

OpenRef

Organize with folders and 25-color labels, read and highlight in the built-in tabbed PDF viewer, and search across titles, abstracts, and full PDF text (English & CJK) with bilingual UI.

CHROME EXTENSION

OpenRef Capture

Click once on any paper page. Extracts DOI/PMID to resolve authoritative metadata and fetches the PDF directly from your authenticated browser session.

WORD ADD-IN

OpenRef for Word

Insert citations and generate bibliographies in Microsoft Word. Switch seamlessly across ~10,000 CSL styles (Vancouver, AMA, Radiology, and more) offline.

AI / MCP

openref-mcp & CLI

Let Claude Code or Claude Desktop search your library, read PDF full text, add highlight annotations, and organize labels — protected by automatic pre-write DB snapshots.

Features

Built for bibliographic accuracy and data ownership

OpenRef never trusts scraped web page metadata, and never locks your library in a third-party cloud.

Authoritative PubMed / Crossref resolution

Every item is verified against official registries and stored as canonical CSL-JSON. Retracted papers are flagged automatically.

Full-text search across PDFs & notes

Instant SQLite FTS5 search over titles, authors, abstracts, notes, and extracted PDF text — including CJK phrase matching.

Paperpile / Zotero migration & Google Drive

Import Paperpile JSON exports or drag-and-drop PDFs from Zotero in bulk. Optionally store and auto-organize PDF files on Google Drive (All Papers/).

100% local on your Mac

All metadata, PDFs, and annotations live inside a single local directory. Zero accounts, zero subscriptions, and no LLM API keys stored in the app.

Install

Install everything with a single command

Paste one line in Terminal to install the app, background connector daemon, CLI, MCP server, Chrome extension folder, and Word add-in.

1

Open Terminal

Press ⌘ + Space to open Spotlight, type Terminal, and press Return.

2

Copy and run the installer command

curl -fsSL https://openref.unitedradiology.jp/install.sh | bash
macOS may prompt once for your login password to trust the local localhost certificate used by the Word citation add-in.
3

Done — OpenRef launches automatically

Once you see "✅ インストール完了!", follow the quick steps below to enable the Chrome extension, Word add-in, or Claude MCP.

Enable the Chrome Extension (OpenRef Capture)

  1. Open chrome://extensions in Chrome
  2. Turn on Developer mode in the top-right corner
  3. Click Load unpacked and select OpenRef Capture inside your home Applications (~/Applications/OpenRef Capture) folder

Use it in Word

  1. Quit Microsoft Word (⌘Q) and open it again
  2. The OpenRef tab appears right after References on the ribbon — and stays there every time you start Word

Connect to Claude Code / Claude Desktop (Optional)

Register openref-mcp (schema / sql / call) with Claude Code in one command:

claude mcp add -s user openref "$HOME/Library/Application Support/OpenRef/bin/openref-mcp"

Migrating from Paperpile / Zotero & Google Drive Sync

Migrate from Paperpile

  1. Export your library in Paperpile via Settings > Export > JSON
  2. Run the command below to import all metadata and folder hierarchies and automatically link existing PDFs on Google Drive
"$HOME/Library/Application Support/OpenRef/bin/openref" import paperpile ~/Downloads/Paperpile.json

Migrate from Zotero

  1. Open ~/Zotero/storage in Finder and search for .pdf to select your PDFs (or export PDFs from Zotero)
  2. Drag & drop them directly into the OpenRef window (or click + New ▾ > Import PDF files)
  3. OpenRef extracts DOIs/PMIDs from the first pages and resolves authoritative metadata via PubMed & Crossref
You can also keep using the Zotero Connector Chrome extension with OpenRef (just quit the Zotero desktop app).

Store PDFs on Google Drive

With Google Drive for Desktop, OpenRef can store and organize your PDFs directly on Google Drive (OpenRef/All Papers/, or existing Paperpile/All Papers/) as Author Year - Title.pdf for easy access from iPad or other devices.

  1. In OpenRef's top menu bar, choose Settings > PDF storage > Google Drive
  2. To move existing local PDFs to Drive, click Move local PDFs to Google Drive in the same menu
The SQLite DB itself stays safely on local Mac storage (also available via CLI: openref cutover enable / migrate-managed).

Uninstall

One command removes the app and services while keeping your library data. For updating, see About updates below.

curl -fsSL https://openref.unitedradiology.jp/uninstall.sh | bash
Updates

About updates

OpenRef never rewrites itself. It only tells you that a new version exists — whether and when to install it is your call.

The banner shown at the top of the app when a new version exists: version number, install command, Copy button and ×
The banner when a new version is available (example: 9.9.9). Copy puts the command on the clipboard; × hides the banner until the next launch.
1. KNOW

Checked at launch

At launch, at most once a day, OpenRef reads a one-line version file from this site. If it is newer than what you are running, a banner appears at the top of the app. Only the running version number is sent — nothing from your library, no identifiers. The very first launch runs one check before you can change the setting.

2. UPDATE

Re-run the install command

Click Copy on the banner, paste into Terminal, press Return. The app, connector daemon, CLI, MCP server, Chrome extension and Word integration are updated together. Your papers, PDFs, annotations and settings are kept.

3. OPT OUT

Turn the check off

Uncheck Settings › Check for updates on launch in the menu bar and OpenRef never contacts this site again (any banner disappears immediately). You can still update by hand with the same command whenever you like.

curl -fsSL https://openref.unitedradiology.jp/install.sh | bash
Before updating: the installer quits OpenRef to replace it, so save any note you are editing first. If Word is installed, macOS may ask for your login password (to trust the local certificate used by the Word citation feature). If Word is open, quit it (⌘Q) and reopen to get the new ribbon. Restart Claude Code / Claude Desktop to pick up the new MCP server. On chrome://extensions, press Reload on OpenRef Capture to pick up the new extension (same folder as the first load).
Safety & Privacy

Your library stays on your Mac

Local SQLite storage, loopback-only daemon, read-only SQL authorizer for AI agents, and zero telemetry.

Free forever Open source (MIT) No telemetry No account required 127.0.0.1 loopback only

External network endpoints

  • eutils.ncbi.nlm.nih.gov — PubMed metadata & retraction lookups
  • api.crossref.org / doi.org — DOI metadata & resolution
  • pmc-oa-opendata.s3.amazonaws.com — Open-access PDF retrieval
  • api.unpaywall.org — OA PDF lookup (opt-in only when OPENREF_EMAIL is set)
  • citation-style-language (GitHub) — On-demand CSL style downloads
  • openref.unitedradiology.jp — Update check (at launch, at most once a day; reads a one-line version file; can be turned off in Settings)

Only identifiers (DOI/PMID/PMCID) are sent when resolving papers. No analytics. The update check at launch (at most once a day) only reads the version number from the distribution site and sends no identifiers; turn it off in Settings › Check for updates on launch.

Everything the installer touches

  • /Applications/OpenRef.app — Desktop app (ad-hoc signed)
  • ~/Library/Application Support/OpenRef/bin/ — openref-connectd, openref (CLI), openref-mcp
  • ~/Library/LaunchAgents/dev.openref.connectd — Local daemon bound strictly to 127.0.0.1
  • ~/Applications/OpenRef Capture/ — Unpacked Chrome extension
  • If Word is installed: OpenRef.dotm in Word's Startup folder (the OpenRef ribbon tab), the citation picker in ~/Library/Application Support/OpenRef/word/, and login keychain trust for the localhost cert

No root/sudo filesystem modifications. Inspect install.sh directly before running.