🎓 ScholarMesh
One query. Forty academic sources. Zero API keys to start.
Federated academic research retrieval over MCP — fan one (or many) keywords out to 40 scholarly sources in parallel, deduplicate by DOI, keep provenance, and get honest failures when a source says no.
🇬🇧 English · 🇮🇩 Bahasa Indonesia · 📦 PyPI
✨ Why ScholarMesh?
| 🧵 Federated by design | search_papers runs 1–8 keywords × 30+ sources in parallel (pool of 8), dedups by DOI → normalized title, and tags every result with alsoIn (where else it appeared) and matchedQueries (which keyword hit it) |
| 🔓 Free-first | 18 sources run with zero keys; 10 more unlock with a free registration; premium indexes stay dormant until you set env vars |
| 📅 Date-bounded everywhere | year_from / year_to pass natively to APIs that support it and apply as a universal post-filter everywhere else — no leaks |
| 🏷 A catalog you can query | every source carries category (free / bot-wall / key), disciplines, and countries metadata — list_sources filters by all three |
| 🟢 Honest failures | bot-walls and rate limits come back as structured blocked envelopes with a manual-fallback URL — never a silent lie |
| 🧩 Agent skill included | skills/research — literature scans, claim verification, proof & argument verification, falsification hunts, numeric sanity checks |
🚀 60-second start
Step 1 — install (requires uv):
uv tool install scholarmesh
Step 2 — connect your MCP client, then restart it:
// ZCode & modern clients (tested shape)
{
"scholarmesh": {
"type": "stdio",
"command": "uvx",
"args": ["scholarmesh"]
}
}
Other clients — Claude Desktop, Cursor, VS Code, Codex CLI
// Claude Desktop & Cursor (mcpServers wrapper)
{
"mcpServers": {
"scholarmesh": { "command": "uvx", "args": ["scholarmesh"] }
}
}
| Client | Config location |
|---|---|
| ZCode | Settings → MCP servers |
| Claude Desktop | macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json |
| Cursor | ~/.cursor/mcp.json (Settings → MCP) |
| VS Code (Copilot) | .vscode/mcp.json — servers sit under a "servers" key |
| Codex CLI | ~/.codex/config.toml → [mcp_servers.scholarmesh] with command = "uvx", args = ["scholarmesh"] |
GUI apps often don't inherit your shell PATH — the uvx form above sidesteps that
entirely. Already uv tool installed? "command": "scholarmesh" works too.
Step 3 — verify & use. Restart the client and all 46 tools appear
(tools/list). From a terminal you can also probe:
scholarmesh # prints: 46 tools, 40 sources ready (stdio) — Ctrl+C exits
uv tool upgrade scholarmesh
uv tool uninstall scholarmesh
💬 What you can just ask
| You say | ScholarMesh runs |
|---|---|
| "Survey 2024+ work on LLM watermarking and AI-text detection — all free sources" | search_papers — parallel queries:[] + year_from, cross-source dedup |
| "Full text of PMC7159299" | europepmc_fulltext — OA JATS XML → clean text |
| "Biomed papers on CRISPR base editing, 2025+" | europepmc_search / pubmed_search + year filter |
| "Proof of the Pythagorean theorem + its prerequisites" | proofwiki_search → proofwiki_get |
| "Math papers reviewing Ricci flow" | zbmath_search (MSC-classified reviews) |
| "Reviewers' take on this OpenReview submission?" | openreview_search → openreview_notes |
| "Code implementations for image-classification papers" | pwc_search |
| "Resolve this DOI + find an OA copy" | crossref_doi → unpaywall_resolve |
| "Cari jurnal Indonesia soal pertanian" | garuda_search / neliti_search / brin_search |
📦 What a result actually looks like (trimmed)
{
"status": "ok",
"source": "federation",
"count": 2,
"items": [
{
"title": "…",
"authors": ["…"],
"year": 2024,
"doi": "10.…",
"venue": "…",
"abstract": "…",
"url": "https://doi.org/10.…",
"pdf": "https://…/paper.pdf",
"source": "openalex",
"extra": { "cited_by_count": 42 },
"alsoIn": ["crossref", "semantic_scholar"],
"matchedQueries": ["LLM watermarking"]
}
],
"meta": { "…": "coverage per keyword, year filter, skipped sources" }
}
Every tool returns the same envelope: status · source · count · items[] · meta.
alsoIn = other sources holding the same paper (deduped); matchedQueries = which
of your keywords matched. Bot-walled sources return {"status": "blocked"} with a
manual-fallback URL.
🌐 40 sources · 46 tools
| Category | Sources |
|---|---|
| 🟢 FREE — 18, on by default | OpenAlex · Crossref · arXiv · DOAJ · OpenReview · Hugging Face Papers · Unpaywall · Zenodo · DataCite · OSF · OpenAIRE · INSPIRE-HEP · ERIC · zbMATH Open · Europe PMC · PubMed · NSSD (China SSH) · ORCID |
| 🟡 FREE, bot-wall — 12, on by default, honest errors | Semantic Scholar · Papers with Code · Google Scholar · GARUDA 🇮🇩 · SINTA 🇮🇩 · OneSearch 🇮🇩 · RAMA 🇮🇩 · Moraref 🇮🇩 · Neliti 🇮🇩 · BRIN 🇮🇩 · ProofWiki · ScienceDB 🇨🇳 |
| 🔑 API KEY — 10, dormant until env set | CORE (free registration) · NASA ADS · AlphaXiv · Scopus · The Lens · Dimensions · Web of Science · Baidu Scholar 🇨🇳 · AMiner 🇨🇳 · CSTR 🇨🇳 |
All 46 tools
| Group | Tools |
|---|---|
| Federation | search_papers · list_sources |
| Indexes | openalex_search · crossref_search · crossref_doi · doaj_search · semantic_scholar_search · lens_search ᵏ · dimensions_search ᵏ · scopus_search ᵏ · wos_search ᵏ |
| Preprints | arxiv_search · openreview_search · openreview_notes · alphaxiv_search ᵏ · hf_search |
| Archives | unpaywall_resolve · zenodo_search · datacite_search · osf_search · openaire_search · core_search ᵏ |
| Domain | inspire_search · eric_search · zbmath_search · proofwiki_search · proofwiki_get · pwc_search · europepmc_search · europepmc_fulltext · pubmed_search · ads_search ᵏ |
| Regional | garuda_search · sinta_search · onesearch_search · rama_search · moraref_search · neliti_search · brin_search · google_scholar_search · nssd_search · baidu_scholar_search ᵏ · aminer_search ᵏ · sciencedb_search · cstr_resolve ᵏ |
| People | orcid_works |
ᵏ = needs an env var (see below)
🔑 API keys — all optional; 18 sources need none
| Env var | Source | Note |
|---|---|---|
S2_API_KEY |
Semantic Scholar | removes the 429 rate limit |
OPENALEX_API_KEY |
OpenAlex | dedicated daily budget |
NCBI_API_KEY |
PubMed E-utilities | 3 → 10 req/s (free registration) |
UNPAYWALL_EMAIL |
Unpaywall | politeness email (optional) |
CORE_API_KEY |
CORE | free registration — deepest OA full-text index |
ADS_TOKEN |
NASA ADS | free for researchers |
ALPHAXIV_API_KEY |
AlphaXiv | or add their official MCP directly |
SCOPUS_API_KEY |
Scopus | needs institutional entitlement |
LENS_TOKEN / DIMENSIONS_TOKEN / WOS_API_KEY |
Lens / Dimensions / WoS | subscription/approval-based |
BAIDU_API_KEY / AMINER_API_KEY / CSTR_CLIENT_ID+CSTR_SECRET |
Baidu / AMiner / CSTR | China platforms |
Wire them via your client's env block or .env.example.
🧩 Companion skill: research
skills/research/ ships with the repo — copy it into your agent's
skills directory and it auto-triggers on research-grade tasks:
- 🔎 Literature scans — field→source routing, two time windows, reading order, gap finding
- ✅ Claim verification — does a claimed result exist, and what is its real status?
- 🧮 Proof & argument verification — math, formal logic, CS correctness, legal reasoning, philosophy — validity vs soundness
- ⚔️ Counterexample / falsification hunts — formal, doctrinal, empirical
- 🔢 Numeric sanity checks — falsify fast; never prove
git clone https://github.com/DranxX/scholarmesh && cd scholarmesh
cp -r skills/research ~/.zcode/skills/ # or ~/.claude/skills/ etc.
Details: skills/README.md.
🏗 Architecture
pyproject.toml ← uv package ([project.scripts] scholarmesh)
└── src/scholarmesh/
├── server.py ← MCP stdio entry (official `mcp` SDK, lowlevel Server)
├── registry.py ← flat SOURCES list, auth-gating, universal year post-filter
├── federation.py ← search_papers: queries×sources parallel (pool 8), dedup, provenance
├── core.py ← httpx w/ timeout, standardized item schema, envelopes, year filter
└── sources/ ← grouped by FUNCTION; geography = metadata per source
├── indexes.py (8) OpenAlex Crossref DOAJ S2 Lens Dimensions Scopus WoS
├── preprints.py (4) arXiv OpenReview(2) AlphaXiv HF Papers
├── archives.py (6) Unpaywall Zenodo DataCite OSF OpenAIRE CORE
├── domain.py (8) INSPIRE ERIC zbMATH ProofWiki(2) PwC EuropePMC(2) PubMed ADS
├── regional.py (13) GARUDA SINTA OneSearch RAMA Moraref Neliti BRIN GScholar NSSD Baidu AMiner ScienceDB CSTR
└── people.py (1) ORCID
🧪 Testing
uv run python tests/light_smoke.py # no-key smoke: gates + stdio + 3 tiny calls
uv run python tests/light_smoke.py --offline # zero network
uv run python tests/e2e_all_tools.py # full live suite (44 tools + federation + stdio)
The full suite runs ~48 checks — every connector tool one by one (envelope-shape
validation + per-category status expectations), three federation modes, year-filter
leak checks, and the MCP stdio handshake. Scraper sources returning blocked count
as PASS: the envelope is the contract, not the network mood. Last run: 47/47 PASS.
❓ FAQ
Why does a source come back blocked?
Some platforms (Google Scholar, ProofWiki, several regional portals) sit behind bot protection. ScholarMesh doesn't pretend otherwise — you get a structured envelope explaining what happened plus the exact URL to try manually. It's a working answer, not an error.
Do I need any API key?
No. 18 sources work keyless. Keys only raise rate limits (Semantic Scholar, PubMed) or unlock premium curated indexes (Scopus, WoS, Lens…).
What happened to paper-research-mcp?
That was this project's first name. The package was renamed to scholarmesh; the
old PyPI name is retired and no longer updated. Install via uv tool install scholarmesh.
🤝 Contributing
Issues and PRs welcome — see CONTRIBUTING.md for the probe-first connector checklist, the test suite, and the release process.
📄 License
MIT. Connector plan distilled from a curated reference doc (Reference.md) plus
live-verified additions (Europe PMC, PubMed, OpenAIRE, Zenodo, DataCite, OSF, zbMATH,
HF Papers, CORE).
Built by DranxX — if ScholarMesh saved you a research all-nighter, a ⭐ is appreciated.
Metadata
Release files for scholarmesh 0.5.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| scholarmesh-0.5.5.tar.gz | 133.0 kB | Without provenance | Details for scholarmesh-0.5.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| scholarmesh-0.5.5-py3-none-any.whl | Python 3 | none | any | Details for scholarmesh-0.5.5-py3-none-any.whl |
Total release size: 176.2 kB
Release files / scholarmesh-0.5.5.tar.gz
| Download URL | scholarmesh-0.5.5.tar.gz |
|---|---|
| Size | 133.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
36ea76d6edf9af49b8b2071381b22d51a0435035df3c88ad93769d39f01a43ce
|
|
BLAKE2b-256 checksum How to use checksums |
ac42cd8f247bf7b2c14f39a02d8aba4f2e033d668f8e7a60301205c1853535eb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / scholarmesh-0.5.5-py3-none-any.whl
| Download URL | scholarmesh-0.5.5-py3-none-any.whl |
|---|---|
| Size | 43.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
08eb45830e38bde8486de5f90a50735a6f8a02b8b781d0a03c070acd561f9758
|
|
BLAKE2b-256 checksum How to use checksums |
857f1ec0bcd1eb7d95ec07dd6039009b7a3674689656a7faed47a9f0441a5df7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for scholarmesh 0.5.5
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.