OmniScholar

English | 简体中文

OmniScholar adds literature search, local Zotero reading, PDF parsing, citation tools, materials data, and scientific image generation to coding agents through a local Python MCP server.

It can search public indexes, combine online records with your Zotero notes, send an approved PDF to MinerU, and publish Markdown into a regular folder or an Obsidian vault. Zotero access is read-only.

Features

• Search Semantic Scholar, OpenAlex, PubMed/PMC, arXiv, Crossref, Unpaywall, easyScholar, Google Scholar, and Google Patents
• Retrieve paper details, authors, citations, references, recommendations, snippets, datasets, and journal metrics
• Read Zotero collections, items, notes, annotations, attachments, indexed text, and local PDF paths without changing the library
• Parse selected PDFs with MinerU and keep text, formulas, tables, and figures together
• Find citation candidates, check bibliographic identity, and format accepted references
• Query Materials Project and export JSON, CSV, Markdown, or CIF
• Generate or edit scientific illustrations with configured image services
• Preserve local Markdown edits and place incoming conflict versions in .conflicts/

OmniScholar exposes 38 tools. See the tool list.

Install

Python 3.11 or newer is required:

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

For development from a source checkout, replace the package name with ..

The distribution name is luffysolution-omnischolar; the command and Python package are omnischolar.

Check the installation:

omnischolar --version
omnischolar doctor --json

Update or uninstall the Python command:

uv tool upgrade luffysolution-omnischolar
uv tool uninstall luffysolution-omnischolar

Connect an agent

Codex app and Codex CLI plugin

Install uv first, then add the OmniScholar Git marketplace and install the plugin:

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

In the ChatGPT desktop app, restart the app, open Plugins, select the OmniScholar marketplace, and install or enable OmniScholar. In Codex CLI, run /plugins to browse the same marketplace.

The plugin bundles all eight Skills and starts its local MCP server from the latest PyPI release:

uvx --from luffysolution-omnischolar@latest omnischolar mcp

No separate pip install is required for this plugin path. @latest asks uvx to resolve the latest package instead of pinning this plugin to a release number. Provider credentials and optional service settings remain in your OmniScholar configuration; plugin installation does not collect them.

Claude Code plugin

Install uv first. In Claude Code, add the GitHub marketplace and install the plugin:

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

For scripts or a regular terminal, use the non-interactive shell commands:

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

Run /reload-plugins if the install summary asks for it, then start a new session. The plugin automatically starts the latest uvx MCP server and exposes namespaced Skills such as /omnischolar:scholar-search. No separate Python installation is required.

Host configuration installer

Preview the files that will change, then install the local MCP entry and Skills:

omnischolar install --dry-run claude
omnischolar install claude

Replace claude with codex, cursor, opencode, hermes, pi, or workbuddy. Codex, Claude Code, Cursor, OpenCode, Pi, and WorkBuddy/CodeBuddy support both user and project scopes. Hermes supports user-level MCP configuration; project-level installation adds Skills and reports that MCP setup is manual.

omnischolar install cursor --scope project
omnischolar update cursor --scope project
omnischolar uninstall cursor --scope project

For Pi, the full installer runs pi install npm:@luffysolution/omnischolar-pi and installs the bundled Skills separately. The npm Extension starts the matching PyPI MCP through uvx, discovers its tools, and registers them with Pi; a separate global Python CLI installation is not required. You can also install the Extension directly:

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

WorkBuddy/CodeBuddy uses ~/.codebuddy/.mcp.json for user scope and .mcp.json for project scope. It does not publish a portable Skills path, so its installer configures MCP and reports Skills as manual_required.

The direct latest MCP command is:

uvx --from luffysolution-omnischolar@latest omnischolar mcp

Normally the agent starts this process from its MCP configuration. The installer checks initialize, tools/list, and omnischolar_status after writing a supported configuration.

Full host and update instructions are in Installation.

Standalone Skills CLI

Plugins already bundle their declared Skills. Use the official Skills CLI separately when you want to install the repository's Skills directly into an agent:

# User scope; replace codex with claude-code, pi, cursor, or another supported agent
npx skills add luffysolution-svg/omnischolar --skill '*' --agent codex --global --yes
npx skills update --global --yes
npx skills remove --skill '*' --agent codex --global --yes

Try it

Find five recent reviews about solid-state battery interfaces. Deduplicate by DOI and show open-access copies.

Find this DOI in my Zotero library and summarize my notes and annotations without changing Zotero.

After I approve the upload, parse this PDF with MinerU and save a reading note in my Obsidian vault.

Query stable Li-Fe-P-O materials in Materials Project and export the selected records as CSV and CIF.

Create a labelled illustration of this mechanism. Treat it as a draft, not experimental data.

Configuration

On the first MCP start or installer run, if no discoverable config exists, OmniScholar creates a complete user-level omnischolar.config.json template with all service sections and credential fields. You can also create it explicitly with omnischolar config init. API keys may be entered directly as apiKey; apiKeyEnv is an optional alternative when you prefer environment variables.

Customize the Obsidian output location, paper folders, Markdown files, and parsed image assets with output.rootDirectory, output.literatureDirectory, output.folderNameTemplate, output.filenameTemplate, output.filenameSeparator, and output.assetFilenameTemplate; see literature and output configuration.

A small local configuration can start with Zotero and the output directory:

{
  "schemaVersion": 1,
  "runtime": { "workspaceRoots": ["./research-inputs"] },
  "zotero": {
    "enabled": true,
    "baseUrl": "http://127.0.0.1:23119/api"
  },
  "output": { "rootDirectory": "./research-output" }
}

OpenAlex, PubMed, arXiv, and Crossref work without API keys. Other services are enabled separately. Configuration fields and provider examples are in Configuration.

Files, uploads, and charges

• Zotero requests go only to the local API on port 23119 and use GET.
• MinerU receives a PDF only when allowExternalUpload is enabled in the config and confirmed again in that tool call.
• Image services receive prompts and any reference images selected for upload. Generation may use account credit.
• Ai4Scholar calls may use account credit. A stored key does not by itself approve a paid call.
• A failed paid request is not retried automatically when the provider may already have accepted it.
• Generated images are illustrations. They are not measurements, experimental evidence, or scientific results.

See PRIVACY.md and Configuration before enabling uploads or paid services.

Included Skills

Documentation

• Installation and agent setup
• Configuration and service credentials
• Literature, Zotero, MinerU, citations, and output
• Materials and chemistry
• Scientific image providers
• Tool list

Support and license

OmniScholar is open source under the MIT License. Open a GitHub issue or email LuffySolution@gmail.com. Remove keys, signed URLs, private paper content, and personal Zotero data before sending a report.

Third-party services and datasets keep their own terms and licenses. See THIRD_PARTY_NOTICES.md.