ads_mcp.client — ADS HTTP Client

HTTP client for the SAO/NASA Astrophysics Data System (ADS) API.

This module provides a thin, async wrapper around the ADS REST API (https://github.com/adsabs/adsabs-dev-api). All network I/O is performed with httpx so it plays nicely with FastMCP’s async event loop.

Example

Basic usage with an async context manager:

async with ADSClient(api_key="my-token") as client:
    result = await client.search("black hole accretion", rows=5)
    print(result)
ads_mcp.client.ADS_BASE_URL = 'https://api.adsabs.harvard.edu/v1'

Base URL for all ADS v1 API requests.

ads_mcp.client.DEFAULT_SEARCH_FIELDS = 'bibcode,title,author,year,abstract,doi,arxiv_class,identifier,citation_count,read_count,pub,volume,page,keyword'

Default fields returned by the search endpoint.

exception ads_mcp.client.ADSError(status_code, message)[source]

Bases: Exception

Raised when the ADS API returns a non-2xx response.

status_code

HTTP status code returned by the server.

message

Human-readable error description.

Parameters:

  • status_code (int)

  • message (str)

__init__(status_code, message)[source]
Parameters:

  • status_code (int)

  • message (str)

class ads_mcp.client.ADSClient(api_key=None, timeout=30.0)[source]

Bases: object

Async HTTP client for the ADS API.

Wraps the ADS REST API endpoints into straightforward async methods. An API key is required; obtain one at https://ui.adsabs.harvard.edu/user/settings/token.

Parameters:

  • api_key (str | None) – ADS API bearer token. If None, the value of the ADS_API_TOKEN environment variable is used.

  • timeout (float) – Request timeout in seconds. Defaults to 30.

Raises:

ValueError – If no API key is provided and ADS_API_TOKEN is not set in the environment.

Example

async with ADSClient() as client:
    papers = await client.search("exoplanet atmospheres", rows=10)
__init__(api_key=None, timeout=30.0)[source]
Parameters:
async search(query, fields='bibcode,title,author,year,abstract,doi,arxiv_class,identifier,citation_count,read_count,pub,volume,page,keyword', rows=10, start=0, sort='date desc')[source]

Search the ADS database.

Calls GET /v1/search/query.

Parameters:

  • query (str) – Solr/ADS query string, e.g. "author:Einstein relativity".

  • fields (str) – Comma-separated list of fields to return.

  • rows (int) – Maximum number of results. Capped at 2000 by ADS.

  • start (int) – Offset into the result set (for pagination).

  • sort (str) – Sort order, e.g. "citation_count desc".

Return type:

dict[str, Any]

Returns:

Parsed JSON response from ADS containing response.docs and response.numFound.

Raises:

ADSError – If ADS returns a non-2xx status.

async export(bibcodes, fmt='bibtex')[source]

Export one or more records in a bibliographic format.

Calls POST /v1/export/{fmt}.

Parameters:

  • bibcodes (list[str]) – List of ADS bibcodes to export.

  • fmt (str) – Export format. One of bibtex, bibtexabs, ris, endnote, procite, refworks, aastex, icarus, mnras, soph, dcxml, refxml, ads, medlars, votable.

Return type:

str

Returns:

The exported bibliography as a plain string.

Raises:

ADSError – If ADS returns a non-2xx status.

async metrics(bibcodes, types=None)[source]

Retrieve citation and usage metrics for a set of papers.

Calls POST /v1/metrics.

Parameters:

  • bibcodes (list[str]) – List of ADS bibcodes to retrieve metrics for.

  • types (list[str] | None) – Optional list selecting which metric types to return. Allowed values: "basic", "citations", "indicators", "histograms", "timeseries". If None, all metrics are returned.

Return type:

dict[str, Any]

Returns:

Parsed JSON metrics object from ADS.

Raises:

ADSError – If ADS returns a non-2xx status.

async search_by_bibcode(bibcodes, fields='bibcode,title,author,year,abstract,doi,arxiv_class,identifier,citation_count,read_count,pub,volume,page,keyword', rows=2000)[source]

Retrieve records for a list of bibcodes via a big-query POST.

Calls POST /v1/search/bigquery.

Parameters:

  • bibcodes (list[str]) – List of ADS bibcodes.

  • fields (str) – Comma-separated list of fields to return.

  • rows (int) – Maximum number of results.

Return type:

dict[str, Any]

Returns:

Parsed JSON response from ADS.

Raises:

ADSError – If ADS returns a non-2xx status.

async get_references(bibcode, rows=200)[source]

Fetch the reference list of a paper.

Uses the references() operator in the ADS search API.

Parameters:

  • bibcode (str) – ADS bibcode of the paper whose references are requested.

  • rows (int) – Maximum number of references to return.

Return type:

dict[str, Any]

Returns:

Parsed JSON search response from ADS.

Raises:

ADSError – If ADS returns a non-2xx status.

async get_citations(bibcode, rows=200)[source]

Fetch the papers that cite a given paper.

Uses the citations() operator in the ADS search API.

Parameters:

  • bibcode (str) – ADS bibcode of the paper whose citations are requested.

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

Return type:

dict[str, Any]

Returns:

Parsed JSON search response from ADS.

Raises:

ADSError – If ADS returns a non-2xx status.