pm-search

PubMed Basic Search

Search PubMed for papers using keyword(s). Returns result count and structured result list via the NCBI E-utilities API — no login, no CAPTCHA, no DOM scraping.

Requirements

• Path 1 (default): python3 + network access to eutils.ncbi.nlm.nih.gov. No browser needed.
• Path 2 (fallback): a browser automation tool that can (a) navigate to a URL and (b) evaluate JavaScript in the page. Any such tool works (Chrome DevTools MCP, Playwright MCP, etc.) — do not assume a specific tool name.

Arguments

$ARGUMENTS contains the search keyword(s) in English or Chinese.

Steps

Path 1 — Standalone script (default)

Run from this skill's directory (single tool call):

python3 scripts/pubmed_api_search.py "YOUR_KEYWORDS" --limit 20

Useful flags: --page N, --sort date|relevance|pub_date|first_author|journal, --year-from 2022 --year-to 2026, --json (machine-readable), --mailto [email protected] (or env NCBI_MAILTO, joins NCBI's polite pool).

The script retries once on 429/5xx and reports failures to stderr with exit code 1. Exit code 0 with total: 0 means the query genuinely matched nothing.

Path 2 — Browser evaluate (only when no shell is available)

Use your browser tool to navigate to https://pubmed.ncbi.nlm.nih.gov/?term={URL_ENCODED_KEYWORDS}&size=20 (this shows the results page to the user), then evaluate the following script in the page. It calls the E-utilities API from page context — it never scrapes DOM.

Replace YOUR_KEYWORDS with the actual search terms:

async () => {
  const query = "YOUR_KEYWORDS";
  const page = 1, size = 20;
  const retstart = (page - 1) * size;

  // E-utilities esearch: get PMID list
  const searchResp = await fetch(
    `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=${encodeURIComponent(query)}&retmax=${size}&retstart=${retstart}&retmode=json&sort=relevance`
  );
  const searchData = await searchResp.json();
  const ids = searchData.esearchresult?.idlist || [];
  const total = parseInt(searchData.esearchresult?.count || '0');
  const queryTranslation = searchData.esearchresult?.querytranslation || '';

  if (ids.length === 0) return { query, total: 0, results: [] };

  // E-utilities esummary: batch get metadata
  const sumResp = await fetch(
    `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=pubmed&id=${ids.join(',')}&retmode=json`
  );
  const sumData = await sumResp.json();

  const results = ids.map((id, i) => {
    const r = sumData.result?.[id] || {};
    const doi = (r.articleids || []).find(a => a.idtype === 'doi')?.value || '';
    return {
      n: retstart + i + 1,
      pmid: id,
      title: r.title || '',
      authors: (r.authors || []).map(a => a.name).join(', '),
      journal: r.fulljournalname || '',
      source: r.source || '',
      pubdate: r.pubdate || '',
      volume: r.volume || '',
      issue: r.issue || '',
      pages: r.pages || '',
      doi,
      pubtype: (r.pubtype || []).join(', ')
    };
  });

  return { query, queryTranslation, total, page, size, results };
}