ads_mcp.server — MCP Server

FastMCP server exposing SAO/NASA Astrophysics Data System (ADS) tools.

This module defines the mcp FastMCP application and registers every ADS tool as an MCP tool handler. Each tool is a thin wrapper around ADSClient.

The server is configured via environment variables (see Configuration Reference). The most important is ADS_API_TOKEN, which must be set to a valid ADS API token.

Running the server

Start the server directly:

python -m ads_mcp.server

or via the installed script:

ads-mcp

Both use stdio transport by default (suitable for MCP hosts such as Claude Desktop, Cursor, or VS Code Copilot).

Available tools

Tool name

Description

search_ads()

Full-text / keyword / author search

get_abstract()

Full metadata + abstract for a bibcode

get_references()

Reference list of a paper

get_citations()

Papers that cite a given paper

export_bibtex()

BibTeX export for one or more bibcodes

export_ris()

RIS export for one or more bibcodes

export_citation()

Export in any supported ADS format

find_arxiv()

Look up a paper by arXiv identifier

find_doi()

Look up a paper by DOI

get_metrics()

Citation & usage metrics

get_similar()

Papers similar to a given bibcode

author_search()

Search papers by author name

get_paper_details()

Retrieve a specific set of fields for a paper
async ads_mcp.server.search_ads(query, rows=10, start=0, sort='date desc', fields='')[source]

Search the ADS bibliographic database.

Performs a full Solr/ADS query and returns formatted results. The query syntax follows the ADS search syntax, supporting field operators such as author:, title:, abstract:, year:, property:refereed, etc.

Parameters:

  • query (str) –

    ADS/Solr query string. Examples:

    • "dark matter annihilation"

    • "author:Einstein AND title:relativity"

    • "abs:exoplanet AND year:2020-2024"

    • "bibcode:2023ApJ...946...29W"

  • rows (int) – Number of results to return (1–2000). Defaults to 10.

  • start (int) – Zero-based offset for pagination. Defaults to 0.

  • sort (str) – Sort order, e.g. "citation_count desc", "date asc". Defaults to "date desc".

  • fields (str) – Comma-separated list of ADS fields to return. If empty, a sensible default set is used.

Return type:

str

Returns:

Human-readable summary of matching papers including title, authors, year, bibcode, publication venue, DOI, citation count, and an abstract snippet.

async ads_mcp.server.get_abstract(bibcode)[source]

Retrieve full metadata and abstract for an ADS paper.

Parameters:

bibcode (str) – ADS bibcode of the paper, e.g. "2019ApJ...887L..24M".

Return type:

str

Returns:

Formatted metadata block including title, authors, journal, DOI, arXiv ID, keywords, and the full abstract text.

async ads_mcp.server.get_references(bibcode, rows=50)[source]

Retrieve the reference list of an ADS paper.

Parameters:

  • bibcode (str) – ADS bibcode of the paper whose references to fetch, e.g. "2019ApJ...887L..24M".

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

Return type:

str

Returns:

Formatted list of papers cited by the given bibcode.

async ads_mcp.server.get_citations(bibcode, rows=50)[source]

Retrieve papers that cite a given ADS paper.

Parameters:

  • bibcode (str) – ADS bibcode of the paper whose citing papers to fetch, e.g. "2019ApJ...887L..24M".

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

Return type:

str

Returns:

Formatted list of papers that cite the given bibcode, sorted by date descending.

async ads_mcp.server.export_bibtex(bibcodes)[source]

Export one or more ADS papers as a BibTeX bibliography.

Parameters:

bibcodes (list[str]) – List of ADS bibcodes to export, e.g. ["2019ApJ...887L..24M", "2023A&A...670A..42S"].

Return type:

str

Returns:

BibTeX-formatted string containing all requested entries.

async ads_mcp.server.export_ris(bibcodes)[source]

Export one or more ADS papers in RIS (EndNote/Mendeley) format.

Parameters:

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

Return type:

str

Returns:

RIS-formatted string suitable for import into reference managers such as Zotero, Mendeley, or EndNote.

async ads_mcp.server.export_citation(bibcodes, fmt)[source]

Export ADS papers in a specified bibliographic format.

Parameters:

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

  • fmt (str) –

    Target format. Supported values:

    bibtex, bibtexabs, ris, endnote, procite, refworks, aastex, icarus, mnras, soph, dcxml, refxml, refabsxml, ads, medlars, votable.

Return type:

str

Returns:

Formatted bibliography string in the requested format.

async ads_mcp.server.find_arxiv(arxiv_id)[source]

Look up an ADS paper by its arXiv identifier.

Accepts both the short form (e.g. 2301.07688) and the full form with category prefix (e.g. astro-ph/0612138).

Parameters:

arxiv_id (str) – arXiv paper identifier.

Return type:

str

Returns:

Formatted metadata for the matching paper, including its ADS bibcode, DOI, and abstract.

async ads_mcp.server.find_doi(doi)[source]

Look up an ADS paper by its DOI.

Parameters:

doi (str) – Digital Object Identifier, e.g. "10.3847/2041-8213/ab5c56".

Return type:

str

Returns:

Formatted metadata for the matching paper.

async ads_mcp.server.get_metrics(bibcodes)[source]

Retrieve citation and usage metrics for one or more ADS papers.

Returns basic publication stats, citation counts, and bibliometric indicators (h-index, g-index, etc.).

Parameters:

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

Return type:

str

Returns:

Human-readable summary of the metrics, including total citations, h-index, i10-index, and read counts.

async ads_mcp.server.get_similar(bibcode, rows=10)[source]

Find papers similar to a given ADS paper.

Uses ADS’s similar() operator which performs more-like-this matching based on the paper’s text.

Parameters:

  • bibcode (str) – ADS bibcode of the reference paper.

  • rows (int) – Number of similar papers to return. Defaults to 10.

Return type:

str

Returns:

Formatted list of papers similar to the given bibcode.

Search for papers by a specific author.

The author name is matched using ADS’s author: field operator which handles last-name-first and initials variations.

Parameters:

  • author (str) – Author name, e.g. "Einstein, A" or "van der Hulst, J.M.".

  • rows (int) – Maximum number of results. Defaults to 20.

  • sort (str) – Sort order. Defaults to "citation_count desc" to show the author’s most-cited papers first.

  • refereed_only (bool) – If True, restrict results to refereed journals. Defaults to False.

Return type:

str

Returns:

Formatted list of papers matching the author query.

async ads_mcp.server.get_paper_details(bibcode, fields='')[source]

Retrieve detailed metadata fields for an ADS paper.

Returns a JSON-like representation of all available metadata for the requested paper, useful when specific fields beyond the default set are needed.

Parameters:

  • bibcode (str) – ADS bibcode of the paper.

  • fields (str) – Comma-separated list of ADS fields to return. If empty, a comprehensive default set is used. Available fields include: abstract, aff, author, bibcode, citation_count, doi, identifier, keyword, pub, title, year, and many more.

Return type:

str

Returns:

Human-readable key-value summary of all requested metadata fields.

ads_mcp.server.main()[source]

Start the ADS MCP server using stdio transport.

This function is called when the package is run as a script (python -m ads_mcp.server) or via the ads-mcp console script.

Return type:

None