README.md
An MCP server for the NASA Astrophysics Data System (ADS)
mcp-server-ads
A powerful MCP server for the NASA Astrophysics Data System (ADS) — the primary database for astrophysics literature. Search papers, traverse citation graphs forward and backward, export BibTeX, compute metrics, and manage reading lists, all through natural language. Works with Claude Desktop/Code, Cursor, OpenAI Codex, and any MCP-compatible client.
Quick Start
Get an ADS API Token
- Create a free account at NASA ADS
- Log in and go to Settings > API Token
- Click Generate a new key and copy the token
Installation
No separate install step needed — the client configurations below use uvx to automatically fetch and run the server. Just pick your client and go. Requires Python 3.11+ and uv.
Claude Code
claude mcp add --scope user mcp-server-ads -e ADS_API_TOKEN=your-api-token-here -- uvx --from git+https://github.com/cbyrohl/mcp-server-ads mcp-server-ads
Use --scope project instead to share the configuration via .mcp.json in your repo, or omit --scope for local (current project only).
Claude Desktop
Add to your Claude Desktop config:
{
"mcpServers": {
"ads": {
"command": "uvx",
"args": ["--from", "git+https://github.com/cbyrohl/mcp-server-ads", "mcp-server-ads"],
"env": {
"ADS_API_TOKEN": "your-api-token-here"
}
}
}
}
Codex CLI
codex mcp add mcp-server-ads --env ADS_API_TOKEN=your-api-token-here -- uvx --from git+https://github.com/cbyrohl/mcp-server-ads mcp-server-ads
This installs to ~/.codex/config.toml (user-level, available across all projects). For project-scoped config, add the entry to .codex/config.toml in your project root instead.
Standalone / Python API
If you want to install the package directly (e.g. as a Python library or to run the server manually):
# Install with uv
uv tool install git+https://github.com/cbyrohl/mcp-server-ads
# Or with pip
pip install git+https://github.com/cbyrohl/mcp-server-ads
Running from Source
git clone https://github.com/cbyrohl/mcp-server-ads.git
cd mcp-server-ads
uv sync
# Run the server
ADS_API_TOKEN=your-token uv run mcp-server-ads
Configuration
| Environment Variable | Required | Default | Description |
|---|---|---|---|
ADS_API_TOKEN |
Yes | — | API token from ADS |
ADS_API_URL |
No | https://api.adsabs.harvard.edu |
API base URL (override for SciX) |
Tools (11)
Search
| Tool | Description |
|---|---|
ads_search |
Search the ADS database with full query syntax, including citations(), references(), similar(), trending(), and reviews() operators |
ads_bigquery |
Search within a specific set of bibcodes (up to 2000) |
Export & Metrics
| Tool | Description |
|---|---|
ads_export |
Export records in 18+ formats (BibTeX, AASTeX, RIS, CSL, etc.) |
ads_metrics |
Compute citation metrics (h-index, g-index, citation counts, etc.) |
Libraries
| Tool | Description |
|---|---|
ads_library |
Manage libraries: list, get, create, edit, or delete saved paper collections |
ads_library_documents |
Manage documents and notes within a library: add/remove papers, set operations (union, intersection, difference, copy, empty), and note CRUD |
Discovery & Resolution
| Tool | Description |
|---|---|
ads_resolve_links |
Resolve available links for a paper (full text, data, etc.) |
ads_object_search |
Translate astronomical object names to ADS queries (SIMBAD/NED) |
ads_citation_helper |
Suggest papers that should be cited alongside a given set |
ads_resolve_reference |
Resolve free-text reference strings to ADS bibcodes |
Network Visualization
| Tool | Description |
|---|---|
ads_network |
Generate author collaboration or paper citation networks from a set of papers |
Resources
| URI | Description |
|---|---|
ads://fields |
Complete reference of searchable and returnable ADS fields |
ads://syntax |
ADS query syntax quick-reference with examples |
ads://rate-limits |
Live API rate-limit status |
Prompts
| Prompt | Description |
|---|---|
literature_review |
Multi-step literature review workflow for a research topic |
citation_analysis |
Citation network analysis workflow for a set of papers |
generate_bibliography |
Generate a formatted bibl |
Tools (11)
ads_searchSearch the ADS database with full query syntax.ads_bigquerySearch within a specific set of bibcodes.ads_exportExport records in 18+ formats like BibTeX, AASTeX, RIS, and CSL.ads_metricsCompute citation metrics including h-index and g-index.ads_libraryManage libraries to list, get, create, edit, or delete paper collections.ads_library_documentsManage documents and notes within a library.ads_resolve_linksResolve available links for a paper such as full text or data.ads_object_searchTranslate astronomical object names to ADS queries.ads_citation_helperSuggest papers that should be cited alongside a given set.ads_resolve_referenceResolve free-text reference strings to ADS bibcodes.ads_networkGenerate author collaboration or paper citation networks.Environment Variables
ADS_API_TOKENrequiredAPI token from ADSADS_API_URLAPI base URL (override for SciX)Configuration
claude_desktop_config.json
{"mcpServers": {"ads": {"command": "uvx", "args": ["--from", "git+https://github.com/cbyrohl/mcp-server-ads", "mcp-server-ads"], "env": {"ADS_API_TOKEN": "your-api-token-here"}}}}Try it
→Perform a literature review on the latest research regarding black hole accretion disks.
→Generate a bibliography in BibTeX format for the top 10 most cited papers on dark matter.
→Find the h-index for the author with bibcode 2023ApJ...950L...1A.
→Create a new library called 'Supernova Research' and add the last 5 papers found in my search.
→Generate a citation network visualization for the papers related to the James Webb Space Telescope.