@pipeworx/nasa-ads

The NASA Astrophysics Data System — essentially the complete bibliography of astronomy and astrophysics since 1823, with hand-curated citation and reference graphs.

Part of Pipeworx — an MCP gateway connecting AI agents to 1679+ live data sources.

Tools

• ads_search(query, sort?, limit?, start?, include_abstract?) — search the literature with the full ADS query syntax (author:"Rubin, V", year:2020-2024, bibstem:ApJ, abs:"phrase", property:refereed).
• ads_paper(identifier) — the full record for one paper by bibcode, DOI or arXiv id. The identifier form is detected and searched in the right field, so a DOI never silently free-text matches an unrelated paper.
• ads_citations(bibcode, direction?, sort?, limit?, start?) — papers citing this one (citations, default) or its bibliography (references).

Auth

BYO only. Pass _apiKey. There is no keyless path: ADS Bearer-authenticates every endpoint and an unauthenticated request is a flat 401 Missing "Authorization" in headers (verified 2026-09-17). The refusal says "requires an API key" so a caller is not left reading a 401 as our outage.

The token is free and generous: create an account at https://ui.adsabs.harvard.edu/ then Settings → API Token (https://ui.adsabs.harvard.edu/user/settings/token).

Platform fallback: PLATFORM_ADS_TOKEN. Until that secret is set, the pack-manifest entry carries byoExpected: true; remove it in the same change that lands the value.

Data sources

• https://api.adsabs.harvard.edu/v1/search/query — every tool here is one call to this endpoint with a different q. ads_citations uses ADS's own citations(bibcode:...) and references(bibcode:...) operators rather than a separate endpoint.

Traps

• fl is not optional in practice. Omit it and ADS returns bare ids with no title, author or year — a clean 200 that looks like a stripped result set. Every call here sends an explicit field list.
• Unquoted author names are searched as free text. author:Rubin is not an author search; author:"Rubin, V" is. A free-text match returns plausible, wrong papers with no error, so the zero-result note says this explicitly.
• Year ranges are year:2020-2024. year>2020 is a syntax error.
• A bibcode is exactly 19 characters, dot-padded (2015ApJ...808...50A). A copy that lost its padding to reflowing matches nothing, which is indistinguishable from "this paper is not indexed".
• Zero citations is usually real. For a paper published in the last few months an empty citations result is ordinary; so is an unknown bibcode. Both return zero rather than an error, so the note names both causes.

Quick Start

Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "nasa-ads": {
      "url": "https://gateway.pipeworx.io/nasa-ads/mcp"
    }
  }
}

What this endpoint actually serves

tools/list at https://gateway.pipeworx.io/nasa-ads/mcp returns the tools in the table above plus the shared Pipeworx meta-tools — ask_pipeworx, discover_tools, search_within, remember/recall and the rest of the gateway-wide set. So the tool count you see is larger than this table: a single-pack endpoint currently lists roughly 30 shared tools alongside the pack's own. The connection's initialize response states its exact scope, and is the authoritative answer for a given day.

This is deliberate, not multiplexing by accident. The meta-tools are what let a scoped connection answer a question this pack does not cover — via ask_pipeworx, which routes across the whole catalog — without you adding a second MCP server. There is currently no way to mount a pack endpoint without them; if the extra schemas cost you more context than the routing is worth, connect to the full gateway once rather than to several pack endpoints.

Or connect to the full Pipeworx gateway to get every pack's tools listed directly, instead of just this one's:

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

Both URLs reach the same gateway and the same 1679+ data sources. The only difference is which pack's tools are listed directly; ask_pipeworx reaches all of them from either one.

No MCP client? Call it over HTTP

curl -X POST https://gateway.pipeworx.io/v1/tools/ads_search \
  -H 'Content-Type: application/json' \
  -d '{"query":"abs:\"dark energy\" property:refereed","sort":"citation_count desc","limit":20}'

No account needed for the first calls. Inspect any tool: GET https://gateway.pipeworx.io/v1/tools/ads_search. Find one: POST https://gateway.pipeworx.io/v1/tools/search_packs with {"query":"..."}.

Standalone (no gateway account)

This package also runs as a local stdio MCP server — no Pipeworx account, no gateway round-trip:

{
  "mcpServers": {
    "nasa-ads": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-nasa-ads"]
    }
  }
}

Or run it directly to confirm it starts:

npx -y @pipeworx/mcp-nasa-ads

It speaks MCP over stdin/stdout and answers initialize/tools/list/tools/call for only this pack's tools — none of the shared meta-tools the gateway connection above adds. Same source, same tools, no ask_pipeworx routing.

Using with ask_pipeworx

Instead of calling tools directly, you can ask questions in plain English — this works on the pack endpoint above as well as on the full gateway:

ask_pipeworx({ question: "your question about Nasa Ads data" })

The gateway picks the right tool and fills the arguments automatically.

More

• Docs and guides
• pipeworx.io

License

MIT