OmniScholar

简体中文 | English

OmniScholar 通过本地 Python MCP 服务，为 Codex、Claude Code、Cursor、OpenCode、Hermes 和 Pi 提供文献检索、Zotero 读取、PDF 解析、引用处理、材料数据和科研绘图工具。

它可以把在线文献记录与 Zotero 笔记放在一起处理，将经你确认的 PDF 交给 MinerU 解析，再把 Markdown 保存到普通文件夹或 Obsidian Vault。Zotero 全程只读。

功能

检索 Semantic Scholar、OpenAlex、PubMed/PMC、arXiv、Crossref、Unpaywall、easyScholar、Google Scholar 和 Google Patents
查询论文详情、作者、参考文献、施引文献、推荐、全文片段、数据集和期刊指标
读取 Zotero 收藏夹、条目、笔记、批注、附件、索引文本和本地 PDF 路径，不修改文献库
按全文游标、图表、公式、段落、文献对比和文献综述模式读取已解析文献，避免整篇正文一次进入上下文
使用 MinerU 提取指定 PDF 的正文、公式、表格和图片
查找引用候选，核对书目信息，再按要求生成参考文献
查询 Materials Project，并导出 JSON、CSV、Markdown 或 CIF
调用已配置的图片服务生成或编辑科研示意图
保留手工修改过的 Markdown，把待合并版本放入 .conflicts/

OmniScholar 共提供 38 个工具，完整列表见工具目录。

安装与部署

需要 Python 3.11 或更高版本。普通 Python 命令任选一种方式安装：

uv tool install luffysolution-omnischolar
# 或
pipx install luffysolution-omnischolar
# 或
python -m pip install luffysolution-omnischolar

检查、更新和卸载：

omnischolar --version
omnischolar doctor --json
uv tool upgrade luffysolution-omnischolar
uv tool uninstall luffysolution-omnischolar

如果希望用一条命令强制刷新并重装最新版：

uv tool install --reinstall luffysolution-omnischolar

Codex 插件

codex plugin marketplace add luffysolution-svg/omnischolar --ref main
codex plugin add omnischolar@omnischolar

# 更新已安装的 Codex 插件
codex plugin marketplace upgrade omnischolar
codex plugin remove omnischolar@omnischolar
codex plugin add omnischolar@omnischolar

ChatGPT 桌面应用中重启应用后打开 Plugins，选择 OmniScholar 并安装或启用；Codex CLI 可运行 /plugins 浏览插件。插件已经包含 Skills，并通过下面的命令启动 PyPI 最新 MCP：

uvx --refresh-package luffysolution-omnischolar --from luffysolution-omnischolar@latest omnischolar mcp

Claude Code 插件

在 Claude Code 会话中运行：

/plugin marketplace add luffysolution-svg/omnischolar
/plugin install omnischolar@omnischolar

普通终端也可以运行：

claude plugin marketplace add luffysolution-svg/omnischolar
claude plugin install omnischolar@omnischolar --scope user
claude plugin update omnischolar@omnischolar --scope user

Pi Extension

pi install npm:@luffysolution/omnischolar-pi
pi update npm:@luffysolution/omnischolar-pi
pi remove npm:@luffysolution/omnischolar-pi

通用安装器与独立 Skills

omnischolar install --dry-run claude
omnischolar install claude
omnischolar update claude
omnischolar uninstall claude

也可以使用官方 Skills CLI 单独安装 Skills；插件已经包含这些 Skills，通常不需要重复安装：

npx skills add luffysolution-svg/omnischolar --skill '*' --agent codex --global --yes
npx skills update --global --yes
npx skills remove --skill '*' --agent codex --global --yes

完整的各 Agent 路径、项目级安装和故障排查见安装说明。

Agent 配置提示词

可以将下面的提示词作为 Agent 的项目级指令或系统提示词基础：

你是我的科研助理，使用 OmniScholar 完成文献检索、Zotero 阅读、PDF 解析、引用核对和科研资料整理。检索时优先使用可靠的学术来源，核对 DOI 与书目信息，并明确区分原文证据、推断和不确定内容。Zotero 只允许读取，禁止修改。上传 PDF、参考图或发起可能收费的请求前必须先征得我的确认；MinerU 只有在我确认后才能上传文件。将确认后的文献笔记和生成文件保存到配置的输出目录，保留已有手工修改，并报告最终文件路径。生成的科研图片只能作为示意图，不能当作实验数据或科研证据。

配置与 MCP 示例

首次启动 MCP 或运行安装器时，如果没有可发现的配置，OmniScholar 会创建用户级 omnischolar.config.json 模板。模板中的服务默认处于启用状态；填写 API key 后即可使用对应服务，没有凭据的服务不会自动发起请求。API key 可以直接填写到 apiKey，也可以用 apiKeyEnv 指定环境变量。

填写对应 API key 并启用服务后，即可直接使用 Ai4Scholar、图片生成、MinerU 和参考图上传。

根目录的 mcp.json 是可直接复制到支持 MCP 的 Agent 中的 stdio 示例，内容如下：

{
  "mcpServers": {
    "omnischolar": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--refresh-package", "luffysolution-omnischolar", "--from", "luffysolution-omnischolar@latest", "omnischolar", "mcp"]
    }
  }
}

mcp.json 只负责启动 MCP，不保存 API key；服务凭据和 Obsidian 输出位置填写在 omnischolar.config.example.json 对应字段中，可执行 omnischolar config init 创建实际配置。插件内部使用的配置文件是 .mcp.json。文件夹、Markdown 文件和图片附件命名可通过 output 区块自定义，详见文献与输出配置。

使用示例

查找 5 篇关于固态电池界面的近期综述，按 DOI 去重，并给出开放获取版本。

在我的 Zotero 中找到这个 DOI，汇总笔记和批注，不要修改 Zotero。

我确认上传后，用 MinerU 解析这份 PDF，并把阅读笔记保存到 Obsidian Vault。

查询 Materials Project 中稳定的 Li-Fe-P-O 材料，将选中的记录导出为 CSV 和 CIF。

为这个机理绘制带标签的示意图。图片只是草稿，不得写成实验数据。

文档

支持与许可证

OmniScholar 使用 MIT License 开源。可以在 GitHub Issues 提交问题，或发送邮件到 LuffySolution@gmail.com。报告问题前，请删除 API key、签名 URL、私人论文内容和个人 Zotero 数据。

第三方服务和数据遵循各自的条款与许可证，详见 THIRD_PARTY_NOTICES.md。

Metadata

Release files for luffysolution-omnischolar 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for luffysolution-omnischolar 0.2.0
File	Size	Uploaded
luffysolution_omnischolar-0.2.0.tar.gz	251.5 kB	Sep 17, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for luffysolution-omnischolar 0.2.0
File	Interpreter	ABI	Platform	Reset
luffysolution_omnischolar-0.2.0-py3-none-any.whl 163.5 kB Sep 17, 2026	Python 3	none	any	Details

Total release size: 415.0 kB

Release files / luffysolution_omnischolar-0.2.0.tar.gz

Download URL	luffysolution_omnischolar-0.2.0.tar.gz
Size	251.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`114a69e12dfc0c8273a716f1bc88d69131ac326b132e1e84a1b2a926914718a4`
BLAKE2b-256 checksum How to use checksums	`41740ced1c507636a3db9afd708eac603251ba7fb69996094ab5c438fde0b8c4`
Upload date	Sep 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/luffysolution-svg/omnischolar
Publishing commit: github.com/luffysolution-svg/omnischolar/tree/9dd91c8d52746bbe722eab40bf257cdc9ceb39d7

Workflow

Publishing configuration: github.com/luffysolution-svg/omnischolar/blob/9dd91c8d52746bbe722eab40bf257cdc9ceb39d7/.github/workflows/publish-npm.yml
Publishing logs: github.com/luffysolution-svg/omnischolar/actions/runs/35247934023/attempts/1

Artifact

Subject: luffysolution_omnischolar-0.2.0.tar.gz
SHA-256 checksum: 114a69e12dfc0c8273a716f1bc88d69131ac326b132e1e84a1b2a926914718a4 Verifying attestations

Release files / luffysolution_omnischolar-0.2.0-py3-none-any.whl

Download URL	luffysolution_omnischolar-0.2.0-py3-none-any.whl
Size	163.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`85f620a15e63d8e90e3b5e048768f418716176f1a0395aa12c58164f482b7c09`
BLAKE2b-256 checksum How to use checksums	`343429a27d8f6ba075e5b034249a1847a00bc1483b2741e0d64bbfc6884601a7`
Upload date	Sep 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/luffysolution-svg/omnischolar
Publishing commit: github.com/luffysolution-svg/omnischolar/tree/9dd91c8d52746bbe722eab40bf257cdc9ceb39d7

Workflow

Publishing configuration: github.com/luffysolution-svg/omnischolar/blob/9dd91c8d52746bbe722eab40bf257cdc9ceb39d7/.github/workflows/publish-npm.yml
Publishing logs: github.com/luffysolution-svg/omnischolar/actions/runs/35247934023/attempts/1

Artifact

Subject: luffysolution_omnischolar-0.2.0-py3-none-any.whl
SHA-256 checksum: 85f620a15e63d8e90e3b5e048768f418716176f1a0395aa12c58164f482b7c09 Verifying attestations