research-hub

Turn your research stack into an AI-operable workspace.
Use Zotero, Obsidian, and NotebookLM together, or start with any two. research-hub gives your AI assistant a real CLI, MCP server, REST API, and dashboard for repeatable literature workflows.

Traditional Chinese: README.zh-TW.md | Watch the full-res mp4

Why this exists

Most research tools are good at one part of the workflow:

• Zotero stores citations, metadata, and PDFs.
• Obsidian stores notes, links, and synthesis.
• NotebookLM turns source bundles into AI-readable briefs.

The painful part is the handoff. research-hub connects those handoffs so an AI agent can search, ingest, tag, summarize, repair, brief, and inspect your workspace without turning your library into an opaque RAG box.

You do not need all three tools on day one.

What it does

research-hub is a local-first orchestration layer for research workflows:

• CLI: research-hub auto, import-folder, ask, doctor, tidy, clusters, zotero, notebooklm, crystal, and more.
• MCP server: lets Claude Desktop, Claude Code, Cursor, Continue.dev, Cline, Roo Code, OpenClaw, and other MCP hosts operate the same workflow.
• REST API: exposes /api/v1/* for browser-only or HTTP-capable assistants.
• Dashboard: gives humans a live view of clusters, papers, diagnostics, briefs, writing support, and management actions.
• Vault format: writes normal Markdown, frontmatter, .base dashboards, cache files, and logs that you can inspect directly.

The core loop:

topic or source folder
  -> discover or import sources
  -> enrich metadata
  -> write Zotero tags/notes when enabled
  -> write Obsidian Markdown notes and cluster dashboards
  -> bundle/upload/generate with NotebookLM when enabled
  -> cache answers as crystals and structured memory

Install + first run

Option A: preview without accounts

pip install research-hub-pipeline
research-hub dashboard --sample

No Zotero, no NotebookLM, no API keys. This opens the end-state dashboard on a bundled sample vault.

Option B: local-first Obsidian workflow

If you mainly use Obsidian and local files:

pip install research-hub-pipeline[import,secrets]
research-hub setup --persona analyst
research-hub import-folder ./papers --cluster my-local-review
research-hub serve --dashboard

Add NotebookLM later with [playwright] if you want browser-based brief generation.

Option C: full Zotero + Obsidian + NotebookLM workflow

pip install research-hub-pipeline[playwright,secrets]
research-hub setup
research-hub auto "your research topic"

For a first smoke test without NotebookLM automation:

research-hub auto "your research topic" --no-nlm

Let your AI install it

Paste this into Claude Desktop, Claude Code, Cursor, Continue, ChatGPT, Gemini, or another shell-capable AI:

Please install research-hub on my machine. It is a Python package that turns
Zotero, Obsidian, and NotebookLM into an AI-operable research workspace.

1. Check `python --version`. If it is below 3.10, tell me to upgrade first.
2. Run `pip install research-hub-pipeline[playwright,secrets]`.
3. Run `research-hub setup`. Stop and pass me the prompts as they appear.
   Answer the Zotero question on my behalf only if I already told you.
   Chrome-based NotebookLM login may open; I will finish it.
4. Ask me for a topic and run `research-hub auto "TOPIC"`.

Python 3.10+ is required. Optional extras: [playwright] for NotebookLM, [import] for local PDF/DOCX/MD/TXT/URL ingest, [secrets] for OS-keyring credential storage, [mcp] for MCP server dependencies.

Connect your AI host

For Claude Desktop, Cursor, Continue.dev, Cline, VS Code Copilot, OpenClaw, or another MCP host:

{ "mcpServers": { "research-hub": { "command": "research-hub", "args": ["serve"] } } }

Restart the host. Then ask naturally:

Find me 5 papers on agent-based modeling and put them in a notebook.

The AI can call auto_research_topic(topic="agent-based modeling", max_papers=5) and ingest papers, generate a NotebookLM brief, and update the vault.

Install host-specific skill files:

research-hub install --platform claude-code
research-hub install --platform cursor
research-hub install --platform codex
research-hub install --platform gemini

Browser-only or HTTP-capable AIs can use the REST API:

curl -X POST http://127.0.0.1:8765/api/v1/plan \
     -H "Content-Type: application/json" \
     -d "{\"intent\":\"research harness engineering\"}"

Full reference: MCP tools and AI integrations.

Dashboard tour

research-hub serve --dashboard opens http://127.0.0.1:8765/.

Overview: treemap over clusters, storage map, and health summary.

Library: per-cluster drill-down with papers, sub-topics, and per-paper actions.

Diagnostics: grouped drift alerts and readiness checks.

Manage: CLI actions as buttons, inline result drawer, confirmation modal, and per-paper row actions.

Briefings and Writing tabs are also available. See the dashboard walkthrough and persona variants.

Inside Obsidian

Every ingested paper becomes a real Markdown note with structured frontmatter. Every cluster can also get an Obsidian Bases dashboard.

Cluster Bases dashboard: generated .base file with sortable paper metadata.

Per-paper note: title, authors, year, DOI, Zotero key, tags, status, cluster, and verification metadata.

Crystals are plain Markdown notes under hub/<cluster>/crystals/*.md, so they can be linked, searched, and read by MCP tools at very low token cost.

Inside Zotero

Every ingested paper gets a namespaced tag set so you can filter your library by research-hub context:

Every paper can also get a child note with Summary / Key Findings / Methodology / Relevance, derived from the Obsidian frontmatter. Papers that were in Zotero before research-hub existed can be backfilled with:

research-hub zotero backfill --tags --notes --apply

Feature matrix

vs alternatives

research-hub does not replace Zotero, Obsidian, or NotebookLM. It connects them so an AI agent can operate the workflow.

The practical fit: research-hub is most useful if you already use at least two of Zotero, Obsidian, and NotebookLM and want your AI assistant to run the repetitive steps.

Troubleshooting

For broader checks, run:

research-hub doctor --autofix

Docs + Status + Dev

Docs: First 10 minutes, lazy mode, dashboard walkthrough, MCP tools, personas, NotebookLM setup, import folder, CLI reference, CHANGELOG.

Status:

• Latest: v0.64.2; see CHANGELOG for package history.
• Tests: 1759 passing.
• MCP tools: 83.
• REST endpoints: 12 at /api/v1/*.
• Bundled skills: research-hub and research-hub-multi-ai.

Developer setup:

git clone https://github.com/WenyuChiou/research-hub.git
cd research-hub
pip install -e ".[dev,playwright]"
python -m pytest -q

Contributing: CONTRIBUTING.md. Package on PyPI: research-hub-pipeline. CLI entry point: research-hub.

License

MIT. See LICENSE.