UniArticles MCP Server

中文版本 (Chinese)

Overview

UniArticles(亿文通) is a unified academic literature retrieval server implementing the Model Context Protocol (MCP). Integrates multiple scholarly databases (Scopus, ArXiv) and literature APIs (PubMed) into a single, standardized API for LLM agents (like Claude).

Features

• Unified Interface: Single search structure for all sources.
• Multi-Source Support:
  • Scopus: Search, abstract details, journal/serial title lookup by ISSN, quota check.
  • ScienceDirect: Full-text article retrieval, article object (figures/tables/supplementary materials) metadata retrieval.
  • ArXiv: Search papers, list recent papers, read paper metadata by ID.
  • PubMed (NCBI Entrez): Keyword search, batch summary lookup, related-article discovery, and PMC full-text/citation linkage — direct NCBI E-utilities calls (no third-party wrapper).
  • General academic search (v3.0.0): Crossref, Europe PMC, DOAJ, OpenAIRE, and CORE keyword/DOI lookup across open scholarly catalogs.
• Standardized Returns: Consistent JSON structure (ok, source, query, count, items, error).
• Secure Configuration: API keys managed via environment variables.

Supported Data Sources

UniArticles unifies the following 9 data sources behind one consistent MCP interface, all returning the same normalized JSON shape and all active by default, providing 21 tools. Every source except arXiv is a direct call to the provider's official REST API (via httpx); arXiv is wrapped through the official arxiv Python package.

⚠️ API Key Requirements

This server integrates multiple data sources, and some advanced features require API keys:

1. Elsevier API (Scopus database, Required):
   • How to get: Apply at Elsevier Developer Portal.
   • Restriction: A basic, non-commercial Elsevier API key (no institutional subscription or Insttoken required) is sufficient to use all remaining Elsevier-related tools in this server — apply for free with a personal account at the Elsevier Developer Portal. (The 8 Elsevier-related tools have been verified against a real non-commercial key. The server currently registers 21 tools total covering 9 data sources; the newer non-Elsevier sources do not require this key.)
   • Clarification: Scopus is an Elsevier database. The ELSEVIER_API_KEY configured here is an Elsevier API key and may also be used for other Elsevier API services allowed by your subscription and key scope. (The legacy variable name SCOPUS_API_KEY is still accepted for backward compatibility but is deprecated and will be removed in a future major version.)

Note: Even without the above API key, you can still use other functions normally.

Installation & Usage

Method 1: Direct Integration with LLM Clients (Recommended)

Suitable for Cherry Studio, LM Studio, Claude Desktop, Trae, etc.

This project is published on PyPI, so you can configure it directly without downloading the full source code. Since these LLM clients are already configured with Python and uv environments, no additional downloads are required.

Simply add the following configuration to your client's MCP settings (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "uniarticles-mcp-server": {
      "command": "uvx",
      "args": [
        "--refresh", 
        "uniarticles-mcp"
      ],
      "env": {
        "ELSEVIER_API_KEY": "your_elsevier_api_key_here",
        "ELSEVIER_INSTTOKEN": "your_elsevier_insttoken_here",
        "NCBI_API_KEY": "your_ncbi_api_key_here",
        "CORE_API_KEY": "your_core_api_key_here"
      }
    }
  }
}

About the env fields: Only ELSEVIER_API_KEY is required (for Scopus / ScienceDirect). All the others are optional — if you don't have a given key, delete that entire line (JSON does not allow comments, and the last remaining line must not end with a comma). The optional fields are:

• ELSEVIER_INSTTOKEN — only if your institution issued an Elsevier Institutional Token, for broader Elsevier access.
• NCBI_API_KEY — PubMed works without it; a key only raises the rate limit from 3 to 10 requests/sec.
• CORE_API_KEY — CORE works without it but is heavily rate-limited (~5 requests, then a ~10-minute lockout); a key is recommended.

If you do not want to force refresh the cache package every time you restart, then instead add the following content: (but this will cause you to need to manually update the package when the package is updated)

{
  "mcpServers": {
    "uniarticles-mcp-server": {
      "command": "uvx",
      "args": [
        "uniarticles-mcp"
      ],
      "env": {
        "ELSEVIER_API_KEY": "your_elsevier_api_key_here",
        "ELSEVIER_INSTTOKEN": "your_elsevier_insttoken_here",
        "NCBI_API_KEY": "your_ncbi_api_key_here",
        "CORE_API_KEY": "your_core_api_key_here"
      }
    }
  }
}

📖 Troubleshooting? See: Step-by-Step Configuration Guide

If you encounter MCP error -32000: Connection closed when starting the service, please find the solution in the related Cherry Studio issue: https://github.com/CherryHQ/cherry-studio/issues/3264

Method 2: Local Installation (Advanced)

Requires Python 3.10+ and uv (recommended) or pip. Useful for developers or those who want to modify the source code.

Using uv:

# Clone the repository
git clone https://github.com/your-username/UniArticles_MCPserver.git
cd UniArticles_MCPserver

# Sync dependencies and run
uv sync
uv run uniarticles-mcp

Using pip:

# Clone and setup venv
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

# Run
python -m uniarticles

Configuration

Create a .env file in the project root:

ELSEVIER_API_KEY=your_elsevier_api_key
# Optional. Only if your institution issued an Elsevier Institutional Token
# (broader Elsevier access). Leave unset otherwise.
ELSEVIER_INSTTOKEN=your_elsevier_insttoken
# Optional. NCBI Entrez works without it; setting it only raises the PubMed
# rate limit from 3 to 10 requests/sec (free from NCBI).
NCBI_API_KEY=your_ncbi_api_key
# Optional. CORE works without it but is heavily rate-limited (~5 requests, then
# a ~10-minute lockout); setting it is recommended. Free from https://core.ac.uk/services/api
CORE_API_KEY=your_core_api_key

Project Structure

src/
└── uniarticles/
    ├── server.py        # MCP Server entry point
    └── sources/         # Data source modules
        ├── arxiv.py
        ├── pubmed.py
        ├── scopus.py
        └── ...
pyproject.toml           # Project metadata and dependencies

Verifying the Installation

This project does not ship a separate test suite; verify the installation by launching the server. It communicates over stdio, so on a successful start it stays running and waits silently for JSON-RPC input from a client (press Ctrl+C to exit):

uv run uniarticles-mcp     # if installed via uv
# or
python -m uniarticles      # if installed via pip

If the process starts without import or configuration errors, the installation is working.

Available Tools

The tools are grouped below by data source, one table per source. 21 tools are registered in total, and every one of them is available as long as its source's key (when required) is configured. Every tool returns the same normalized JSON shape (ok, source, query, count, items, error).

Scopus

ScienceDirect

ArXiv

Availability note: the upstream host export.arxiv.org can stall. During the 2026-09-18 sweep, arxiv_paper_detail_by_id and arxiv_latest_paper_list_by_category both hung ~5 minutes and then failed with a connection timeout, while arxiv_paper_search_by_query returned normally from the same host in 1.4s; the stall cleared ~15 minutes later and all three tools worked again. That hang was originally unbounded, because arxiv.Client exposes no timeout parameter at all — only page_size / delay_seconds / num_retries. Since v3.4.0 the client is built with a 15-second per-request timeout plus a 45-second overall deadline, so a stalled upstream now fails fast with one actionable error naming both limits instead of hanging. _verify/arxiv_timeout_check.py reproduces that behaviour offline by pointing the client at a local listener that accepts connections and never answers; if you do hit a real timeout, _verify/arxiv_connectivity_test.py runs a layered DNS→TCP→TLS→HTTP diagnosis to tell an upstream stall apart from a local network problem.

PubMed (NCBI Entrez)

These tools call the NCBI E-utilities directly. They work without a key; setting the optional NCBI_API_KEY (free from NCBI) only raises the rate limit from 3 to 10 requests/sec.

Crossref

Europe PMC

DOAJ

OpenAIRE

CORE

📝 Recommended Prompt: Literature Search

The prompt below turns a vague request into a reproducible multi-source search. Paste it into any MCP client with UniArticles connected, then replace the last line with your own request. Its query-shape rules were verified against the live APIs — the probe results are in project-docs/buildlog.md.

On 2026-09-18 a sweep invoked every registered tool once against the live APIs. OpenAlex (the one source that kept failing that day — its search endpoint returned HTTP 429 under the upstream's anonymous-traffic rate limiting) has since been removed in v3.4.0, and the sweep was then repeated against the remaining source set: 21 tools, 21/21 succeeded.

You are my literature-search assistant. UniArticles MCP tools are connected.
Follow these four steps exactly, in order.

STEP 1 — Split my request BEFORE searching.
Restate what I need as: (a) topic or research question in one sentence;
(b) search type — breadth scan, one specific known paper, or author/venue lookup;
(c) research domain; (d) time window; (e) language; (f) how many papers is enough.

STEP 2 — Rule out the sources that certainly cannot match, and say so out loud.
Apply these rules and skip those sources without calling them:
- Topic is biomedical/life-sciences ONLY -> drop arXiv (wrong domain). Note that
  DOAJ, CORE and OpenAIRE are open-access aggregators across ALL disciplines and
  do cover biomedicine, so do not drop them on domain grounds; whether they are
  dropped depends only on the next rule.
- Topic is physics, mathematics, computer science, statistics, quantitative
  biology or economics -> arXiv is usable; ANY other domain (humanities, social
  sciences, clinical medicine) -> drop arXiv (it is preprint-only and has no
  journal coverage).
- I want peer-reviewed / mainstream / non-open-access journals -> drop DOAJ,
  CORE and OpenAIRE (open-access only, so they bias the result set).
- I want the full text or a PDF -> no UniArticles tool returns full text or
  binaries. Say this up front and keep sources only for metadata plus links.
- I want non-English (e.g. Chinese) literature -> this server indexes no Chinese
  database at all (no CNKI / Wanfang / VIP). Measured with a Chinese query such
  as "深度学习": Crossref, DOAJ and CORE return Chinese-language records, Europe
  PMC returns bracketed English translations of Chinese journal articles, Scopus
  is inconsistent (0~1 hits for the same query), and PubMed and arXiv return 0.
  State that coverage is far below a Chinese database; never claim it replaces
  CNKI or Wanfang.
- Scopus and ScienceDirect -> only usable if ELSEVIER_API_KEY is configured. If a
  call returns an auth/quota error, mark that source unavailable and continue; do
  not silently drop the requirement.
Always keep at least two sources.

STEP 3 — Search the remaining sources in this order, using these query shapes.
1. Scopus — for a known paper use TITLE("exact title"); for a topic use
   TITLE-ABS-KEY(term AND term); count 5-10.
2. Crossref — plain keyword search; also use it to confirm each DOI.
3. PubMed (biomedical only) — for a known paper use  Exact paper title[Title]
   and do NOT wrap it in quotes: the quoted form returns 0 results. Never pass
   a long natural-language sentence; stopwords such as "in" can zero the whole
   query. Put explicit AND between term groups.
4. Europe PMC — same field syntax as PubMed, e.g. TITLE:"exact title".
5. arXiv (preprint domains only) — ti:"exact title" for a known paper,
   all:term for a topic.
6. DOAJ, CORE, OpenAIRE — open-access only. DOAJ's relevance ranking is weak
   and returns off-topic hits for title-like queries, so verify every title
   before reporting it.
7. ScienceDirect — identifier lookup only (DOI/PII). It has NO search tool, so
   never try to search it.
Use 5-10 results per source. Running the same topic against several sources is
the expected pattern, not a fallback chain. Skip any source that errors and
record it.

STEP 4 — Merge and report.
Deduplicate by DOI, then by normalized title. Output ONE Markdown table,
newest first, with exactly these columns:

| Title | Published | Journal / Venue | DOI Link | Source | Summary |

- DOI Link: [10.xxxx/yyy](https://doi.org/10.xxxx/yyy); if there is no DOI,
  use the source's own URL.
- Summary: 1-2 sentences, derived ONLY from an abstract actually returned by a
  tool. If no abstract is available, write "no abstract available". Never
  invent or infer content.
- Source: the tool's `source` value; list every source that returned the paper.
After the table, list which sources you skipped and why, plus any query that
returned 0 results.

My request: <describe what you want here>

Query shapes that are verified to work

🤝 Call for Contributions

Due to the author's background in Chemistry, I am less familiar with databases and API developments in other research fields. I warmly welcome contributions and Pull Requests (PRs) from the community to add more data sources!

⚖️ License & Acknowledgments

License

Dual licensed: AGPL-3.0-or-later or a commercial license

This project is released under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later) — full text in LICENSE. You may use, modify, and redistribute it, including for commercial purposes, provided you comply with the AGPL: if you distribute a modified version, or expose one to users over a network, you must offer those users the corresponding source code.

💼 Commercial licensing: If the AGPL's copyleft obligations do not fit your use case — for example, embedding this server in a closed-source product, or operating a modified version as a network service without publishing your changes — a separate commercial license is available from the author: wangzh685@mail2.sysu.edu.cn.

Note: the earlier wording "AGPL-3.0 with commercial restriction" was inaccurate and has been corrected in v3.4.0. The AGPL does not restrict commercial use; what it restricts is closed-source redistribution and closed-source network deployment.

Special Acknowledgments

• ScopusMCP: ScopusMCP is the first literature retrieval MCP tool the author successfully developed, but initially it was quite bloated and difficult to port.Thanks to my roommate (https://github.com/qwe4559999) for the suggestion to use pypi and uv for packaging.

• ArxivMCPserver: Integrated directly from the ArxivMCPserver project.

Special Declaration

This project uses AI-generated content.