Research workspace for Zotero + Obsidian + NotebookLM. Search, ingest, sync, verify briefs.
io.github.WenyuChiou/research-hub MCP Server
The io.github.WenyuChiou/research-hub MCP server provides a research workspace for Zotero + Obsidian + NotebookLM. It supports searching, ingesting, syncing, and verifying briefs as part of repeatable literature workflows, with an interface intended to operate with AI tooling.
🛠️ Key Features
Research workspace integrating Zotero, Obsidian, and NotebookLM
Search, ingest, sync, and verify briefs
Exposes an MCP server (as described in the project excerpt)
Includes CLI, REST API, and a dashboard (mentioned in the readme excerpt)
🚀 Use Cases
Literature review workflows across the Zotero/Obsidian/NotebookLM stack
Brief validation and routing before downstream tool access
Verifiable, repeatable research steps with recorded results
⚡ Developer Benefits
“AI-operable workspace” for connecting research tools via MCP
Workflow-managed path with durable state, workflow-only policy, checkpoints, and result recording (per excerpt)
⚠️ Limitations
Available integration scope is described only at the stack level (Zotero, Obsidian, NotebookLM); no additional supported tools are listed in the provided data.
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.
research-hub dashboard demo, real screen recording
📚 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
bash
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.
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/<cluster>/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
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:
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:
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.
12-skill portable pack:SKILL.md workflows install directly for Claude Code, Codex, Cursor, and Gemini. The new resumable orchestrator automates low-risk stages and pauses at explicit human gates before external writes, costly experiments, semantic revisions, and release.
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:
text
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.
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.
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.
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/<slug>
Which research cluster the paper belongs to
category/<arxiv-code>
arXiv category like cs.AI or econ.GN
type/<publication-type>
Review, JournalArticle, etc. from Semantic Scholar
src/<backend>
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 notebooklm login opens a browser but Google blocks login
New-device or bot challenge
Complete the visible browser sign-in and phone challenge
research-hub auto finds 0 papers / empty vault
Topic too narrow OR papers were quarantined by the authenticity gate (unresolved DOI, failed integrity, or relevance-unjudged)
Re-run with --max-papers 20 / rephrase; run research-hub quarantine list to see rejected papers + reasons
research-hub auto stops before searching: "no relevance judge on PATH"
Fail-closed relevance check and no supported LLM CLI found
Install a judge CLI, or re-run with --no-fit-check to skip relevance judging
NotebookLM upload or generate fails
NotebookLM UI changed or login expired
Run research-hub notebooklm login --auto-detect; then resume with research-hub notebooklm bundle/upload/generate/download --cluster <slug>
notebooklm upload worked yesterday and now fails on auth
Google's __Secure-1PSIDTS / PSIDRTS cookies expire roughly every 3.5h; notebooklm keepalive cannot refresh them server-side
Re-run research-hub notebooklm login --auto-detect — the browser opens, the cookies refresh on sign-in, the session saves automatically (no terminal interaction). Takes < 1 minute
auto --with-crystals cannot find an LLM CLI
No supported LLM CLI is on PATH
Install one, configure a custom adapter, or use crystal emit and crystal apply manually
Claude Desktop cannot see the MCP server
MCP config is in the wrong file or host was not restarted
Check the host config path and restart Claude Desktop
init reports Zotero warnings but you do not use Zotero
Persona expects Zotero
Re-run research-hub setup --persona analyst or --persona internal
research-hub clusters delete refuses to delete
Cluster has papers, notes, or Zotero items
Re-run with --apply --force after reviewing the cascade preview
research-hub auto errors "cluster already has N papers"
Cluster is non-empty and you ran auto --cluster <slug> without a flag
Add --append to add more, or --force to overwrite
Zotero items miss research-hub tags or notes
Items were created before v0.61 or pipeline failed mid-run
These are platform or design boundaries, not bugs — please do not file
them as issues. They are documented here so you know what to expect and
which workaround to reach for.
Limitation
What's actually happening
What to do
IEEE Xplore PDFs / URLs are blocked by anti-bot
IEEE returns an "Unable to Load Page" HTML stub to direct fetches. paper attach-pdfs can now route configured publisher PDF URLs through your institution's EZproxy and fall back to the direct URL if the proxy fails.
Configure ezproxy_host_suffix (hostname-rewrite mode, recommended for most institutions) or ezproxy_url_template (legacy), run research-hub ezproxy login once, then re-run paper attach-pdfs. See EZproxy PDF access. Without EZproxy, manually attach the PDF through institutional access or skip the source.
NotebookLM session expires ~every 3.5h
Google's short-lived __Secure-1PSIDTS / PSIDRTS cookies are not refreshable by background polling. notebooklm keepalive exists but cannot rotate them server-side.
Re-run research-hub notebooklm login --auto-detect when a run reports an auth failure — < 1 minute, no terminal interaction.
--no-llm-fit-check can't filter "wrong sub-topic, right field"
The no-LLM BM25 gate is designed to catch blatant cross-field contamination (e.g. pure hydrology with zero AI in an LLM cluster). It cannot tell "AI-agents-in-general" from "AI-agents-in-water-resources" — both score similarly on a lexical-only metric, so the gate is recall-biased and keeps both.
For topic-specific subset filtering, use the default LLM-judge path (drop --no-llm-fit-check). The LLM-judge layer is what's designed to make semantic relevance calls.
Cluster-overview LLM auto-fill writes English headings even when the scaffold is Chinese
topic.py writes Chinese section headings (## 核心問題, ## 範圍定義, …) for the empty scaffold, but apply_overview re-renders the file with English headings (## Core Question, ## Scope, …) when the LLM fills it in.
Cosmetic — content is correct. If you prefer Chinese headings on the filled overview, hand-curate the section names after the first auto-fill (the markers ensure subsequent runs preserve your edits).
auto_pipeline() Python API stays opt-in for PDFs (CLI is opt-out)
Programmatic callers — tests, library users — get with_pdfs=False by default so the PDF-attach network round-trips don't fire silently. The CLI hands in True from BooleanOptionalAction.
If you call auto_pipeline() directly and want PDFs attached, pass with_pdfs=True explicitly. CLI users get the default-on behaviour automatically; use --no-with-pdfs to opt out.
Slow / blocked publisher URLs sometimes poison the NotebookLM bundle
Some publishers (Wiley paywalls, Frontiers oddly-routed PDFs, IEEE) return either a thin stub or an HTML error page that the bundle ladder admits because the URL pre-check passed. Downstream NotebookLM grounds on the stub instead of the paper.
Run auto and inspect the [warn] N source(s) look like they did not ingest content block. Replace the listed URLs with PDFs uploaded to the NotebookLM web UI for those papers.
