OmniScholar
Literature, Zotero, PDF, citation, materials, and scientific image tools for research agents.
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 的正文、公式、表格和图片
- 基于 MinerU 原文进行完整或聚焦式专业解读，结合图片视觉内容、图注和正文上下文分析图表；仅在内容过长或用户要求时保存 Markdown
- 查找引用候选，核对书目信息，再按要求生成参考文献
- 查询 Materials Project，并导出 JSON、CSV、Markdown 或 CIF
- 调用已配置的图片服务生成或编辑科研示意图
- 保留手工修改过的 Markdown，把待合并版本放入
.conflicts/ - 将 Zotero PDF、笔记和批注保存到每篇文献的
source/
OmniScholar 共提供 39 个工具，完整列表见工具目录。
安装与部署
需要 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。MinerU 原文与 Zotero 阅读记录都会写入书目信息 frontmatter，解析图片始终以 Zotero key 开头；文件夹、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。
Installation
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
uvx luffysolution-omnischolarSet up in your AI client
Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-luffysolution-svg-omnischolar": {
"command": "uvx",
"args": [
"luffysolution-omnischolar"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencePackage
luffysolution-omnischolarpypiCompatible MCP Clients
OmniScholar works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
- Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect. - Cursor
~/.cursor/mcp.jsonRestart Cursor for changes to take effect. - VS Code
.vscode/mcp.jsonReload VS Code window for changes to take effect. - Windsurf
~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect. - Claude Code
.mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.