mcp -ads

This MCP server provides a comprehensive interface to the NASA ADS database via natural language queries and a suite of tools. It supports searching the ADS catalog, traversing forward and backward citation graphs, exporting results in multiple formats, computing bibliometric metrics, and managing reading libraries. Tools are exposed through the MCP framework and can be accessed from Claude Desktop, Codex CLI, or any MCP-compatible client. The ADS_API_TOKEN must be provided to authenticate with ADS, and an optional ADS_API_URL can be set to point at a custom ADS endpoint. Typical workflows include performing literature searches, exporting citations, building reading lists, and generating metric reports on a set of papers. The server emphasizes token-efficient output and supports integration with several clients for streamlined usage.

Prerequisites:

• Python 3.11+ (for uvx-based or Python-native usage)
• Internet access to fetch the server from GitHub
• ADS API token (registered with NASA ADS)

Option A: Standalone / Python API (via uvx)

1. Install uv (Python self-contained environment helper) if not already installed: https://docs.astral.sh/uv/getting-started/installation/
2. Run the server directly from the repository: git clone https://github.com/cbyrohl/mcp-server-ads.git cd mcp-server-ads uv sync ADS_API_TOKEN=your-token uv run mcp-server-ads

Option B: Claude/Codex integrations (via MCP config)

1. Ensure uvx is installed and accessible in your environment.
2. Use the MCP configuration snippet provided in mcp_config to register the server with your client (Claude Desktop or Codex CLI). The configuration will handle the token via ADS_API_TOKEN environment variable.

Option C: Install as a Python package (standalone install)

1. uv tool install git+https://github.com/cbyrohl/mcp-server-ads
2. Run or integrate as above, providing ADS_API_TOKEN in the environment when starting the server.

Environment variables:

• ADS_API_TOKEN: Required. Obtain from NASA ADS settings.
• ADS_API_URL: Optional. Defaults to https://api.adsabs.harvard.edu; override if using SciX or a custom ADS endpoint.

Tips:

• Keep ADS_API_TOKEN secure; avoid committing it to repositories.
• If using multiple clients, consider using the --scope project or similar scope configuration to share the MCP configuration via .mcp.json.
• When exporting data, explore ads_export for BibTeX, AASTeX, RIS, CSL, and other formats.
• For large bibcode sets (libraries or big queries), use ads_bigquery to constrain results before exporting.

Common issues:

• Token authentication failures: verify the token is active and has the necessary ADS permissions.
• Network or rate-limit errors: check ADS_API_URL and monitor rate limits via the ADS status endpoints.