Skip to content

Full text

These tools write to the local cache, so they're hidden when SCHOLAR_MCP_READ_ONLY=true (the default). Converted Markdown comes back in pages of 20,000 characters by default; see Background jobs for why conversions usually answer with a job handle.

fetch_paper_pdf

Fetch Paper PDF. Changes state, not destructive. Reaches outside the server. Tags: write.

Download the PDF of a paper.

Tries the Semantic Scholar open-access URL first. When that is missing, fails or serves something other than a PDF, it tries alternative sources, one after another: ArXiv (from externalIds), PubMed Central, and Unpaywall (by DOI, requires SCHOLAR_MCP_CONTACT_EMAIL). A failure lists every source tried under attempts.

Skips download if the file already exists locally, which answers immediately; a fresh download usually takes 10-30 seconds and may be returned as a background job handle instead.

Parameters

Name Type Default Description
identifier string required Paper identifier (DOI, S2 ID, ARXIV:, etc.).

Returns

{"path": "...", "source": "..."} on success, or a structured error dict. The source field indicates where the PDF was obtained (s2_oa, arxiv, pmc, unpaywall).

A response looks like {"path": "/data/scholar-mcp/pdfs/<id>.pdf", "source": "s2_oa"}. The error forms are:

  • {"error": "no_oa_pdf"}: no PDF URL found from any source
  • {"error": "download_failed"}: HTTP error downloading the PDF
  • {"error": "not_pdf"}: the response body does not begin with the PDF header

Unless the operator turned access links off, each of these three also carries access_links, a list of {"label", "url"} routes to the paper (by default its doi.org link), and a note for the model. A paper with nothing to fill a route, such as one without a DOI under the default, gets neither.

Paper metadata is read from the same 30-day cache get_paper uses, and a freshly resolved record is written back to it. A repeat call for the same paper needs no Semantic Scholar request.

convert_pdf_to_markdown

Convert PDF to Markdown. Changes state, not destructive. Reaches outside the server. Tags: write.

Convert a local PDF to Markdown using docling-serve.

Works on any local PDF, including manually placed paywalled papers. Returns an error if the server does not have PDF conversion configured.

Conversion typically takes 1-5 minutes depending on page count, so expect a background job handle rather than an inline result; a previously converted file is served from cache immediately.

Tip: start with use_vlm=false (the default). Standard conversion handles most papers well. Only retry with use_vlm=true when the result has garbled formulas or missing figure descriptions.

VLM and standard results are cached separately (<stem>.md vs <stem>_vlm.md), so switching modes never overwrites a previous conversion. When VLM is requested but not configured, the response includes a vlm_skip_reason field explaining why.

Markdown is returned in pages of at most 20,000 characters. When next_offset is present, call this tool again with that value as text_offset; the cached conversion makes later pages inexpensive. Set max_chars to null only when the client can accept the complete document in one response.

Parameters

Name Type Default Description
file_path string required Absolute path to the local PDF file.
use_vlm boolean false Use VLM enrichment for formulas and figures. Falls back to standard conversion if VLM is not configured and reports the reason in vlm_skip_reason.
text_offset integer 0 Character offset at which the Markdown page starts.
max_chars integer \| null 20000 Maximum Markdown characters to return, capped at 20,000. Pass null for the complete text.

Returns

{"markdown": "...", "path": "...", "vlm_used": bool}.

A response looks like {"markdown": "...", "path": "/data/scholar-mcp/md/<name>.md", "vlm_used": true/false}. A vlm_skip_reason reads like "vlm_api_url_not_configured".

VLM enrichment processes each formula and figure image individually via an external vision model, which is slower.

Requires SCHOLAR_MCP_DOCLING_URL to be set. VLM enrichment also requires SCHOLAR_MCP_VLM_API_URL and SCHOLAR_MCP_VLM_API_KEY.

fetch_and_convert

Fetch and Convert Paper. Changes state, not destructive. Reaches outside the server. Tags: write.

Resolve a paper, download its PDF, and convert to Markdown.

Tries the Semantic Scholar open-access URL first, then alternative sources (ArXiv, PubMed Central, Unpaywall) until one serves a PDF; a failure lists every source tried under attempts. Each stage fails gracefully: metadata is always returned if the paper resolves, even if PDF download or conversion fails.

The full pipeline typically takes 1-5 minutes, so expect a background job handle rather than an inline result.

Tip: start with use_vlm=false (the default). Standard conversion handles most papers well. Only retry with use_vlm=true when the result has garbled formulas or missing figure descriptions.

VLM and standard results are cached separately (<id>.md vs <id>_vlm.md), so switching modes never overwrites a previous conversion. When VLM is requested but not configured, the response includes a vlm_skip_reason field explaining why.

Markdown is returned in pages of at most 20,000 characters. When next_offset is present, call this tool again with that value as text_offset; the cached conversion makes later pages inexpensive. Set max_chars to null only when the client can accept the complete document in one response.

Parameters

Name Type Default Description
identifier string required Paper identifier (DOI, S2 ID, ARXIV:, etc.).
use_vlm boolean false Use VLM enrichment for formula/figure extraction. Falls back to standard conversion if VLM is not configured and reports the reason in vlm_skip_reason.
text_offset integer 0 Character offset at which the Markdown page starts.
max_chars integer \| null 20000 Maximum Markdown characters to return, capped at 20,000. Pass null for the complete text.

Returns

metadata and markdown on full success, or metadata plus an error key if a stage fails.

On full success, a response looks like:

{
  "metadata": {"paperId": "...", "title": "...", ...},
  "markdown": "# Paper Title\n...",
  "pdf_path": "/data/scholar-mcp/pdfs/<id>.pdf",
  "md_path": "/data/scholar-mcp/md/<id>.md",
  "pdf_source": "s2_oa",
  "vlm_used": false
}

A successful HTTP response whose body does not begin with %PDF- returns {"error": "not_pdf"} before conversion. The pdf_source field indicates the download source.

The metadata block is read from the same 30-day cache get_paper uses, and a freshly resolved record is written back to it. A call whose PDF and Markdown are both already on disk makes no Semantic Scholar request at all.

See PDF Conversion guide for setup instructions.

fetch_pdf_by_url

Fetch PDF by URL. Changes state, not destructive. Reaches outside the server. Tags: write.

Download a PDF from a URL and optionally convert to Markdown.

Use this when you have found an alternative PDF link (such as one on an author's homepage, a preprint server, or an institutional repository) that is not listed in Semantic Scholar's openAccessPdf field.

The PDF is saved locally and, if docling-serve is configured, converted to Markdown automatically. Conversion typically takes 1-5 minutes and is returned as a background job handle. An already downloaded and converted URL answers immediately.

Markdown is returned in pages of at most 20,000 characters. When next_offset is present, call this tool again with that value as text_offset; the cached conversion makes later pages inexpensive. Set max_chars to null only when the client can accept the complete document in one response.

Parameters

Name Type Default Description
url string required Direct URL to a PDF file.
filename string \| null null Optional filename stem for caching (such as "smith2024_attention"). Derived from the URL if omitted.
use_vlm boolean false Use VLM enrichment for formulas and figures.
text_offset integer 0 Character offset at which the Markdown page starts.
max_chars integer \| null 20000 Maximum Markdown characters to return, capped at 20,000. Pass null for the complete text.

Returns

pdf_path and optionally markdown / md_path.

On success with docling configured, a response looks like:

{
  "pdf_path": "/data/scholar-mcp/pdfs/<filename>.pdf",
  "markdown": "# Paper Title\n...",
  "md_path": "/data/scholar-mcp/md/<filename>.md",
  "vlm_used": false
}

The PDF is cached by filename, so subsequent calls with the same filename return immediately.

The response body must begin with %PDF- before it is cached or sent to docling. A response with another body returns {"error": "not_pdf"} and is not converted. This header check does not validate the complete PDF structure.

Create PDF Upload Link. Destructive. Reaches outside the server. Tags: write.

Create a one-time link for uploading a PDF this server cannot fetch.

Use it when this server could not fetch a paper's PDF and the user can download it through their own library. Send the file as the body of an HTTP PUT to the returned url, outside the conversation. Never read it into the conversation. With an identifier, call fetch_and_convert with the same identifier once the upload is done. Without one, call convert_pdf_to_markdown with the returned pdf_path. If a converted paper turns out to be the wrong document, call this tool again with replace=true: the stored PDF and its conversion are removed at once.

Parameters

Name Type Default Description
identifier string \| null null Paper identifier (DOI, S2 ID, ARXIV:, etc.) the PDF belongs to. Omit it for a document that is not a known paper.
replace boolean false Remove this paper's stored PDF and Markdown before creating the link. Needs an identifier.
ttl_s number \| null null Link lifetime in seconds. Omit it for the server default. Values above the server's maximum are capped.

Returns

url and expires_in_s, plus paper_id with an identifier or pdf_path without one.

The tool exists only on an HTTP deployment with SCHOLAR_MCP_BASE_URL set. For a paper, a response looks like:

{
  "url": "https://mcp.example.com/transfer/<token>",
  "expires_in_s": 3600.0,
  "paper_id": "649def34f8be52c8b66281af98ae884c09aef38b"
}

The file then goes up as the raw body of one request:

curl -X PUT --data-binary @paper.pdf "https://mcp.example.com/transfer/<token>"

After that, fetch_and_convert with the same identifier returns the paged Markdown.