scholar

google_scholar_search_mcp.scholar.require_identifier(title, scholar_id)[source]

Ensure at least one way to identify a paper was given.

Parameters:
  • title (str | None) – Paper title.

  • scholar_id (str | None) – Scholar cluster id (PaperResult.scholar_id).

Raises:

ScholarInvalidArgumentError – If both are empty.

class google_scholar_search_mcp.scholar.ScholarClient(config)[source]

Bases: object

Synchronous wrapper around scholarly that returns typed models.

ensure_available()[source]

Fail fast while Scholar is known to be blocking this client.

Raises:

ScholarBlockedError – During the cooldown after a detected block.

search_pubs(query, max_results=10, year_low=None, year_high=None, sort_by='relevance', patents=True, offset=0)[source]

Search publications by keyword.

Parameters:
  • query (str) – Search query.

  • max_results (int) – Maximum number of papers to return.

  • year_low (int | None) – Earliest publication year.

  • year_high (int | None) – Latest publication year.

  • sort_by (str) – "relevance" or "date".

  • patents (bool) – Whether to include patents.

  • offset (int) – Number of leading results to skip (for paging).

Returns:

list[PaperResult] – Up to max_results papers, starting at offset; empty when the offset is past the last result.

Raises:
  • ScholarBlockedError – If Scholar answers with a bot check instead of results.

  • MaxTriesExceededException – If Scholar blocks the request (raised by scholarly).

Return type:

list[PaperResult]

get_paper_details(title=None, *, scholar_id=None)[source]

Fetch full details and BibTeX of a paper.

Parameters:
  • title (str | None) – Paper title (best search hit is used).

  • scholar_id (str | None) – Scholar cluster id from a search result.

Returns:

PaperDetails – Details of the identified paper.

Raises:
Return type:

PaperDetails

get_citations(title=None, max_results=10, *, scholar_id=None, offset=0)[source]

Fetch papers that cite a paper.

With scholar_id the cited paper is not fetched (saving a request), so its title is None and the total comes from the result page header.

Parameters:
  • title (str | None) – Title of the cited paper.

  • max_results (int) – Maximum number of citing papers to return.

  • scholar_id (str | None) – Scholar cluster id from a search result.

  • offset (int) – Number of leading citing papers to skip (for paging).

Returns:

tuple[str | None, int | None, list[PaperResult]] – The cited paper’s title (if known), its total citation count (if known) and the citing papers.

Raises:
Return type:

tuple[str | None, int | None, list[PaperResult]]

get_bibtex(title=None, *, scholar_id=None)[source]

Get the BibTeX entry of a paper.

Parameters:
  • title (str | None) – Paper title (best search hit is used).

  • scholar_id (str | None) – Scholar cluster id from a search result.

Returns:

str – BibTeX entry.

Raises:
Return type:

str