Research Hub

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.

[](https://pypi.org/project/research-hub-pipeline/) [](pyproject.toml) [](LICENSE) [](https://github.com/punkpeye/awesome-mcp-servers)

[](https://www.zotero.org/) [](https://obsidian.md/) [](https://notebooklm.google.com/)

Traditional Chinese: [README.zh-TW.md](README.zh-TW.md) | [Watch the full-res mp4](docs/demo/dashboard-walkthrough.mp4)

> 📚 Part of the agentic AI learning roadmap — a 7-stage curated path for building agentic AI, multilingual (zh-TW · zh-Hans · English). This workspace is referenced in §13 (research workflow skills).

> 🧪 Real-use signal: in daily use by 1 PhD researcher (Lehigh CEE) tracking 7+ research clusters across Zotero + Obsidian + NotebookLM. Shipping since Apr 2026, docs updated for v0.95.0.

---

Quick start

pip install research-hub-pipeline
research-hub dashboard --sample   # preview with sample data, no accounts needed

For a real research-hub vault with Zotero / Obsidian / NotebookLM integration, pick the install path matching your stack in [§ Start Here](#start-here).

---

Contents

1. [Quick start](#quick-start)
2. [Real Screenshots](#real-screenshots)
3. [Is this for me?](#is-this-for-me--vs-alternatives)
4. [Start Here](#start-here)
5. [First-Run Checklist](#first-run-checklist)
6. [Credential Reference](#credential-reference)
7. [Connect your AI host](#connect-your-ai-host)
8. [Why this exists](#why-this-exists)
9. [What it does](#what-it-does)
10. [Operator Modes](#operator-modes)
11. [Dashboard tour](#dashboard-tour)
12. [Inside Zotero](#inside-zotero)
13. [Feature matrix](#feature-matrix)
14. [Troubleshooting](#troubleshooting)
15. [Known limitations](#known-limitations)
16. [Docs + Status + Dev](#docs--status--dev)
17. [License](#license)

---

Real Screenshots

These are generated by a real research-hub vault, not mockups.

Obsidian paper note: Markdown note with title, authors, DOI, Zotero key, tags, cluster, status, and verification metadata.

Obsidian Bases dashboard: generated .base file with sortable paper metadata and reading status.

Obsidian graph view: managed topic folders and labels can be colored with research-hub vault graph-colors --refresh.

Generated crystals are also plain Markdown notes under hub//crystals/*.md, so they can be linked, searched, and read by MCP tools at low token cost.

---

Is this for me? — vs alternatives

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

| What you can do | Zotero alone | NotebookLM alone | Generic RAG | Obsidian-Zotero plugin | research-hub | |---|---:|---:|---:|---:|---:| | Search arXiv + Semantic Scholar in one command | No | No | DIY | No | Yes | | Ingest into Zotero and Obsidian and NotebookLM | No | No | DIY | Partial | Yes | | AI brief from your collection | No | Manual | DIY | No | Yes | | Cached canonical answers | No | No | Re-fetches | No | Yes | | Structured memory layer | No | No | Usually chunks | No | Yes | | Direct AI-agent control via MCP | No | No | DIY | No | Yes | | Live dashboard with action buttons | No | No | No | No | Yes | | Per-cluster Obsidian Bases dashboard | No | No | No | No | Yes | | No OpenAI/Anthropic API key required | n/a | Yes | Usually no | n/a | Yes | | Local-first vault you own | Partial | No | Depends | Yes | Yes |

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.

---

Start Here

Pick the path with the fewest moving parts. You can add Zotero, NotebookLM, MCP, or AI-host skills later.

| Goal | Accounts needed | Commands | |---|---|---| | Preview the dashboard only | None | pip install research-hub-pipeline then research-hub dashboard --sample | | Try a demo vault | None | pip install research-hub-pipeline then research-hub init --sample | | Work from local PDFs/DOCX/Markdown | Obsidian optional | pip install "research-hub-pipeline[import,secrets]" then research-hub setup --persona analyst | | Zotero + Obsidian, no browser automation | Zotero | pip install "research-hub-pipeline[secrets]" then research-hub setup --skip-login | | Full Zotero + Obsidian + NotebookLM loop | Zotero + Google | pip install "research-hub-pipeline[playwright,secrets]" then research-hub setup | | Autonomous agent bootstrap | Existing vault or target folder | python -m research_hub setup --autonomous --vault ./vault --persona agent |

After setup, run:

research-hub doctor
research-hub serve --dashboard

For the first real ingestion, keep NotebookLM out of the path until Zotero and Obsidian are healthy:

research-hub auto "agent-based modeling" --max-papers 3 --no-nlm

Then enable NotebookLM after the browser login works:

research-hub notebooklm login --auto-detect
research-hub notebooklm bundle --cluster 
research-hub notebooklm upload --cluster 
research-hub notebooklm generate --cluster  --type brief
research-hub notebooklm download --cluster 

research-hub setup also prints these next steps when it finishes.

First-Run Checklist

| Item | Needed when | How to handle it | |---|---|---| | Python 3.10+ | Always | Use the same Python that runs pip install research-hub-pipeline | | Zotero API key + library ID | Zotero-backed paper ingestion | Set ZOTERO_API_KEY and ZOTERO_LIBRARY_ID, then run research-hub doctor | | Obsidian vault | Markdown note workflow | Point setup at a folder you can open in Obsidian; it is still plain Markdown | | NotebookLM browser login | NotebookLM upload/generate/download | Run research-hub notebooklm login --auto-detect; Google OAuth still requires a visible human sign-in | | LLM CLI for relevance judging | research-hub auto default path | Install claude, codex, gemini, opencode, aichat, cursor, configure a custom adapter, or pass --no-fit-check | | AI-host integration | Claude/Codex/Cursor/Gemini/OpenClaw/etc. | Use MCP/REST for tool-calling hosts; use research-hub install --platform ... only for verified skill installer targets |

Credential Reference

These variables are required only for Zotero-backed workflows. Local file import, sample dashboards, MCP server startup, and REST API inspection can run without them.

| Name | Required | Purpose | |---|---|---| | ZOTERO_API_KEY | yes | Zotero web API auth, required for paper ingestion | | ZOTERO_LIBRARY_ID | yes | Zotero library identifier | | SEMANTIC_SCHOLAR_API_KEY | no | Uses an S2 API key and defaults to a conservative ~1 request/sec throttle | | SEMANTIC_SCHOLAR_RPS | no | Optional S2 request-rate override; leave unset unless your key has a different quota | | TAVILY_API_KEY | no | Web search backend (alternative to DDG) | | BRAVE_API_KEY | no | Web search backend (alternative to DDG) |

Semantic Scholar searches are deliberately paced. Without SEMANTIC_SCHOLAR_API_KEY, research-hub uses a slower anonymous delay because public traffic shares capacity. With a key, the default is approximately one request per second and 429 responses are retried with Retry-After / exponential backoff. If Semantic Scholar grants your key a different quota, set SEMANTIC_SCHOLAR_RPS instead of editing code.

Connect your AI host

research-hub has two AI-facing integration layers:

| Layer | Best for | Current status | |---|---|---| | MCP / REST | Claude Desktop, Claude Code, Cursor, Continue.dev, Cline, Roo Code, VS Code Copilot, OpenClaw, and other tool-calling hosts | Host-agnostic; configure the MCP server or call the REST API | | Installed SKILL.md files | Claude Code, Codex, Cursor, Gemini | Built-in installer targets via research-hub install --platform ... | | Manual SKILL.md loading | Hermes, OpenClaw, other agents with skill/rules directories | Copy or reference the bundled skill directories manually; not release-verified as installer targets |

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

{ "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 for the platforms with known default skill directories:

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

OpenClaw, Hermes, and other agents can still use research-hub through MCP/REST. If the host supports SKILL.md-style directories or rules files, copy the bundled directories from skills/ or inline the relevant SKILL.md into the host's instructions. research-hub install --platform does not currently verify those hosts.

Browser-only or HTTP-capable AIs can use the REST API after starting the local server with research-hub serve --dashboard:

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](docs/mcp-tools.md), [AI integrations](docs/ai-integrations.md), [AI host support matrix](docs/ai-host-support.md), and [live smoke checklist](docs/live-smoke.md).

---

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.

| Your current stack | What research-hub gives you first | |---|---| | Zotero + Obsidian | Paper search, Zotero metadata, Markdown notes, tags, Obsidian Bases dashboards | | Obsidian + NotebookLM | Local PDF/DOCX/MD/TXT ingest, cluster dashboards, NotebookLM bundles and briefs | | Zotero + NotebookLM | Zotero-backed paper selection, namespaced tags, NotebookLM upload/generate/download | | Zotero + Obsidian + NotebookLM | Full loop: discover -> ingest -> organize -> brief -> answer -> maintain | | No accounts yet | Sample dashboard and local smoke tests before connecting anything |

---

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.
• Portable skill pack: SKILL.md workflow instructions can be installed directly for Claude Code, Codex, Cursor, and Gemini, or copied manually into hosts that support skill/rules directories.
• 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.
• Authenticity gate (v0.95+): every discovered paper must resolve to a real identifier (DOI / arXiv / PMID), pass integrity and relevance checks, or it is quarantined with a recorded reason and never written to the vault. No fabricated references — inspect rejects with research-hub quarantine list.

The core loop:

topic or source folder
  -> discover or import sources
  -> verify authenticity (resolve + integrity + relevance) or quarantine
  -> 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

---

Operator Modes

research-hub supports both human-first and agent-first setup.

For a human researcher, research-hub setup runs the onboarding wizard, installs host-specific skills when it can detect the host, optionally launches NotebookLM login, and offers a small sample run.

For an autonomous agent or Cowork-style host:

pip install research-hub-pipeline
python -m research_hub describe > capabilities.json
python -m research_hub setup --autonomous --vault ./vault --persona agent
# emits BootstrapReport JSON; exit code 0 if ready, 1 otherwise

Then drive operations via CLI --json mode or the bundled MCP server (research-hub-mcp). All report-shaped commands accept --json; capability introspection lives in research-hub describe.

NotebookLM boundary. NotebookLM upload still requires one-time human-driven browser-based Google OAuth. Headless agents can prepare bundles and read downloaded briefs, but they cannot complete Google's first sign-in or phone challenge by themselves.

Relevance judge boundary. auto_research_topic and research-hub auto run a fail-closed relevance check by default. With no supported LLM CLI and no --no-fit-check, auto stops before search and prints the fix instead of silently producing an empty vault.

| Persona | Best for | Install extra | |---|---|---| | Researcher | STEM papers, DOI/arXiv, Zotero-first workflows | [playwright,secrets] | | Humanities | books, quotes, URL-only sources, Zotero + Obsidian | [playwright,secrets] | | Analyst | industry research, local PDFs/reports, no Zotero required | [import,secrets] | | Internal KM | lab/company knowledge bases, mixed file types | [import,secrets] |

Field presets for discover new, search, and related planning flows are cs, bio, med, physics, math, social, econ, chem, astro, edu, and general. There is no hydrology preset; use general intentionally.

---

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](docs/dashboard-walkthrough.md) and [persona variants](docs/personas.md).

---

Inside Zotero

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

| Tag | Meaning | |---|---| | research-hub | Ingested through this pipeline | | cluster/ | Which research cluster the paper belongs to | | category/ | arXiv category like cs.AI or econ.GN | | type/ | Review, JournalArticle, etc. from Semantic Scholar | | src/ | Search backend that discovered it: arxiv, semantic_scholar, crossref, zotero |

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

| Capability | Command or MCP tool | Notes | |---|---|---| | One-shot setup | research-hub setup | init + install + optional NotebookLM login + guided sample r

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: WenyuChiou
• Source: WenyuChiou/research-hub
• License: MIT
• Homepage: https://pypi.org/project/research-hub-pipeline/

Install and usage instructions live in the source repository linked above.