ads-mcp

ads-mcp is a Model Context Protocol (MCP) server that gives AI assistants direct access to the SAO/NASA Astrophysics Data System (ADS) bibliographic database.

With ads-mcp your AI assistant can:

🔍 Search millions of astronomy, astrophysics, and physics papers
📄 Retrieve abstracts, full metadata, and keywords
🔗 Fetch reference lists and citing papers
📊 Compute h-index, citation counts, and other bibliometric indicators
📚 Export formatted citations in BibTeX, RIS, AASTeX, MNRAS, and more
🆔 Resolve arXiv IDs and DOIs to full ADS records

Quick Start
Available Tools
Configuration
Integration Guides
Documentation
Development
License

Quick Start

1. Get an ADS API key

Create an account at https://ui.adsabs.harvard.edu and generate an API token at https://ui.adsabs.harvard.edu/user/settings/token.

2. Install

From source:

git clone https://github.com/cgarling/ads-mcp.git
cd ads-mcp
pip install -e .

3. Configure

cp .env.example .env
# Edit .env and add your key:
#   ADS_API_TOKEN=your_token_here

4. Run

ads-mcp

The server listens on stdin/stdout (MCP stdio transport) and is ready to be used by any MCP-compatible client.

Available Tools

| Tool | Description | |------|-------------| | search_ads | Full-text / keyword / author search using ADS/Solr query syntax | | 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 (Zotero, Mendeley, EndNote) | | export_citation | Export in any ADS-supported format | | find_arxiv | Look up a paper by arXiv ID | | find_doi | Look up a paper by DOI | | get_metrics | Citation & usage metrics (h-index, g-index, i10, ...) | | get_similar | Papers similar to a given bibcode | | author_search | Search papers by author name | | get_paper_details | Comprehensive metadata for a paper |

See the Tools documentation for full parameter references.

Example queries you can ask your AI assistant

"Find the 10 most-cited papers on gravitational wave detection."

"What are the references of 2019ApJ...887L..24M?"

"Give me the BibTeX for DOI 10.3847/2041-8213/ab5c56."

"How many times has arXiv:2301.07688 been cited?"

"Search for refereed papers by author Einstein published before 1950."

"What papers are similar to 2017ApJ...848L..12A?"

Configuration

Set these environment variables (or put them in a .env file):

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | ADS_API_TOKEN | yes | — | Your ADS API bearer token | | ADS_MCP_LOG_LEVEL | no | WARNING | Python log level (DEBUG, INFO, WARNING, ERROR) |

Never commit your API key to version control. Add .env to your .gitignore.

Integration Guides

GitHub Copilot (Cloud Agent)

TBD

VS Code

VS Code can support MCP definitions at different levels (> = Ctrl+Shift+P on Windows, Cmd+Shift+P on Mac).

workspace: >MCP: Open Workspace Folder MCP Configuration
remote: >MCP: Open Remote User Configuration
global: >MCP: Open User Configuration

Here we use the inputs feature to avoid hard-coding our API token. Upon first starting the server, VS Code will ask you for your API key and store it securely. Start the server with >MCP: List Servers, select ads, and start server -- this will require uv to be installed where the server is running. Note from VS Code docs: MCP servers run wherever they are configured. Servers in your user profile run locally. If you're connected to a remote and want a server to run on the remote machine, define it in the workspace settings or remote user settings (MCP: Open Remote User Configuration).

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ADS_API_TOKEN",
      "description": "ADS API Token",
      "password": true
    }
],
  "servers": {
    "ads": {
      "type": "stdio",
	  "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/cgarling/ads-mcp",
        "ads-mcp"
      ],
      "env": {
        "ADS_API_TOKEN": "${input:ADS_API_TOKEN}"
      },
      "tools": ["*"]
    }
  }
}

Claude Desktop

Edit your Claude Desktop configuration file:

| OS | Path | |----|------| | macOS | ~/.claude/mcp.json | | Windows | %USERPROFILE%\.claude\mcp.json | | Linux | ~/.claude/mcp.json |

{
  "mcpServers": {
    "ads": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/cgarling/ads-mcp",
        "ads-mcp"
      ],
      "env": {
        "ADS_API_TOKEN": "${ADS_API_TOKEN}"
      }
    }
  }
}

Where the environment variable ADS_API_TOKEN must be available to the shell that will run the server.

Restart Claude Desktop after saving.

Cursor

Edit MCP configuration files

| OS | Path | |----|------| | macOS | ~/.cursor/mcp.json | | Windows | %USERPROFILE%\.cursor\mcp.json | | Linux | ~/.cursor/mcp.json |

and add the same json as for Claude Code above.

Generic MCP client

Other MCP clients that support stdio transport should be able to use ads-mcp with json similar to the above, but not all may support secret interpolation "env": {"ADS_API_TOKEN": "${ADS_API_TOKEN}"}.

Documentation

Full documentation is available at https://cgarling.github.io/ads-mcp

Includes setup guide, full tool reference, configuration reference, integration guides, and Python API docs.

Development

git clone https://github.com/cgarling/ads-mcp.git
cd ads-mcp
pip install -e ".[docs,dev]"

# Run tests
pytest

# Build docs locally
python -m sphinx docs docs/_build/html -b html

# Lint
ruff check ads_mcp/

License

MIT — see LICENSE.

ads-mcp is not affiliated with or endorsed by the SAO/NASA Astrophysics Data System.

MCP Servers