NASA ADS MCP Server

A Model Context Protocol (MCP) server that provides seamless access to the NASA Astrophysics Data System (ADS) directly within Claude. Search papers, track citations, manage libraries, and export references — all through natural language conversation.

License: MIT

About this project

This MCP server is the result of an experiment on collaborating with Claude (Anthropic) to augment my literature search workflows. It leveraged the Skill mcp-builder provided by Anthropic. All code was generated by Claude based on requirements, domain knowledge, and iterative feedback provided by the human-in-the-loop. The MCP server is working well for me, but it is far from an extensively tested solution. Feel free to fork, contribute or suggest me things that need fixing or improvement.

Features

This MCP server exposes 10 tools for interacting with NASA ADS:

Search & Discovery

• search_papers - Search ADS with its full query syntax; results show journal, volume, page, DOI and arXiv ID, page through with offset, and can be limited to one collection
• get_paper_details - Abstracts and full metadata for up to 20 papers at once, by bibcode, DOI or arXiv ID
• get_author_papers - Find publications by an author, in the astronomy collection by default, optionally by ORCID, affiliation, author position ("papers where I'm second author"), team size or refereed status

Metrics & Analytics

• get_paper_metrics - Track citations, reads, and impact for specific papers
• get_author_metrics - Calculate h-index, citation statistics, and research impact, with the same options (e.g. refereed papers with at most 20 authors, for a CV)

Reference Management

• export_bibtex - Export properly formatted BibTeX citations
• list_libraries - View your personal ADS paper collections
• get_library_papers - Access papers from specific libraries
• create_library - Organize papers by topic or project
• add_to_library - Build and maintain paper collections

Why This Tool?

The NASA ADS is the primary literature database for astronomy and astrophysics research, containing millions of papers, preprints, and citations. This MCP server makes ADS accessible through conversational AI, enabling:

• Literature reviews without switching contexts
• Citation tracking for your publications
• BibTeX generation for LaTeX/Quarto manuscripts
• Research organization through libraries
• Impact analysis with comprehensive metrics

Perfect for astronomers, astrophysicists, and researchers who want their reference database integrated into their AI workflow.

Installation

Students and first-time users: follow the step-by-step guide, in English or Portuguese.

Prerequisites

• uv, the Python package manager, which also fetches Python for you if needed (install instructions). On Linux and macOS:

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

  After installing, open a new terminal (or restart Claude Code) so uv is on your PATH before you install the plugin. The repository pins Python 3.13 in .python-version, which uv downloads automatically; this avoids very new Python versions that some dependencies don't have prebuilt wheels for yet.
• A NASA ADS API token, free with an ADS account (get yours here)

Where it works

The server runs on your own computer, so it works wherever Claude can start local programs:

Where you use Claude	Works?	How to install
Claude Code (terminal, IDE extensions, desktop app's Code tab), on Linux, macOS, or Windows	✅	Option 1: plugin
Claude Desktop chat (macOS, Windows, Linux beta)	✅	Option 2: one-click bundle
Cowork	Not yet: Cowork doesn't ask for the plugin's token setting
claude.ai on the web, mobile apps	❌ These can't run programs on your computer

Option 1: Claude Code plugin (recommended)

If your organization's Claude plan already provides this plugin, it's installed for you: skip to step 3.

1. Add this repository as a plugin marketplace (a catalog Claude Code can install from):

   claude plugin marketplace add prtc/nasa-ads-mcp
   

2. Install the plugin:

   claude plugin install nasa-ads@nasa-ads-mcp
   

3. Enter your ADS token when Claude Code asks for it. If it didn't ask, or to change it later, run this inside a Claude Code session:

   /plugin configure nasa-ads@nasa-ads-mcp
   

   The token goes into your system's secure credential store. Alternatively, save it in ~/.ads/dev_key (the file the ads Python package uses), and the server will find it there.
4. Start a new Claude Code session and run /mcp: plugin:nasa-ads:nasa-ads should show as connected. The first start can take a minute or more, while uv downloads Python 3.13 (if your computer doesn't have it) and installs the server's dependencies. Claude Code waits only 30 seconds, so /mcp may say "Failed to connect" the first time; give it a minute, then run /reload-plugins or start a new session. To do the slow part ahead of time, run uv python install 3.13 before installing the plugin.

Skipping the permission prompts: Claude Code asks before each tool's first use. To allow the tools for good, add rules to permissions.allow in your settings.json. The plugin's tools are named mcp__plugin_nasa-ads_nasa-ads__<tool>, which differs from a manual setup's mcp__nasa-ads__<tool>, so rules copied from a manual setup don't match. To allow every tool:

"permissions": { "allow": ["mcp__plugin_nasa-ads_nasa-ads__*"] }

Or allow only the tools that read, so Claude still asks before create_library and add_to_library change your ADS libraries: search_papers, get_paper_details, get_author_papers, export_bibtex, get_paper_metrics, get_author_metrics, list_libraries, get_library_papers, each written as mcp__plugin_nasa-ads_nasa-ads__search_papers and so on.

Updating: claude plugin marketplace update nasa-ads-mcp, then claude plugin update nasa-ads@nasa-ads-mcp.

Already set it up by hand before? Remove the old entry so Claude doesn't see every tool twice: claude mcp remove nasa-ads.

Sharing with your research group

On a Claude Team or Enterprise plan, an Owner can install the plugin for every member. The organization's plugin sync reads a private marketplace repository, so create one for your group (for example, in your group's GitHub organization) with a single file, .claude-plugin/marketplace.json, that points at this repository:

{
  "name": "pleiad-astronomy",
  "description": "Claude plugins for the Pleiad Astronomy group",
  "owner": { "name": "Paula Coelho" },
  "plugins": [
    {
      "name": "nasa-ads",
      "source": { "source": "github", "repo": "prtc/nasa-ads-mcp" },
      "description": "Search NASA ADS: papers, metrics, BibTeX export, and your ADS libraries"
    }
  ]
}

Then, in claude.ai, go to Organization settings → Plugins & skills → Add → Sync from GitHub, choose that repository, and set Default access to Installed by default. Members get the plugin in Claude Code as nasa-ads@synced, and each one adds their own ADS token. See Anthropic's guide to syncing plugins from a repository.

Option 2: Claude Desktop (one-click bundle)

1. Download nasa-ads.mcpb from the latest release.
2. Double-click it, drag it into the Claude Desktop window, or go to Settings → Extensions → Advanced settings → Install Extension…
3. Paste your ADS token when Claude Desktop asks for it.

If Claude Desktop reports that it can't find uv, install uv (see Prerequisites) and restart it.

Option 3: Manual setup (Claude Desktop or any MCP client)

1. Clone this repository:

git clone https://github.com/prtc/nasa-ads-mcp.git
cd nasa-ads-mcp

1. Install dependencies:

uv sync

1. Configure your API token:

Create a .env file in the project root:

cp .env.example .env

Edit .env and add your NASA ADS API token:

ADS_API_TOKEN=your_token_here

1. Add to Claude Desktop configuration:

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this entry to the mcpServers section:

{
  "mcpServers": {
    "nasa-ads": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/nasa-ads-mcp",
        "run",
        "python",
        "src/nasa_ads_mcp/server.py"
      ]
    }
  }
}

Replace /absolute/path/to/nasa-ads-mcp with the actual path to where you cloned the repository.

1. Restart Claude Desktop

Check that nasa-ads is listed under Settings > Developer.

Usage Examples

Once connected, you can interact with ADS through natural language in Claude:

Search & Discovery

"Search for recent papers on stellar populations in elliptical galaxies"
"Find papers by Coelho, Paula R. T. from 2020-2025"
"What are the most cited papers on galaxy formation?"

Metrics & Impact

"What's my current h-index and total citations?"
"Show me citation trends for bibcode 2005A&A...443..735C"
"Get metrics for my 2024 papers"

Reference Management

"Export BibTeX for these 5 papers: [bibcodes]"
"Show me what's in my 'Stellar Spectral Libraries' collection"
"Create a new library called 'Review Paper References'"
"Add these papers to my reading list"

API Coverage

This server implements:

• ✅ Search API - Full query capabilities with field-specific searches
• ✅ Metrics API - Author and paper-level metrics
• ✅ Libraries API - Complete CRUD operations for collections
• ✅ Export API - BibTeX citation generation
• ⏳ Journals API - Future enhancement

Development

Project Structure

nasa-ads-mcp/
├── .github/workflows/         # Tests on every pull request; builds the .mcpb for each release
├── .claude-plugin/
│   ├── plugin.json            # Claude Code plugin: metadata, token setting, server command
│   └── marketplace.json       # Lets this repository act as a plugin marketplace
├── manifest.json              # Claude Desktop bundle (.mcpb) manifest
├── assets/                    # Icons (Pleiad logo by Ingrid Beloto; not MIT-licensed)
├── .mcpbignore                # Files left out of the bundle (never .env)
├── docs/                      # Student guides (English and Portuguese)
├── src/
│   └── nasa_ads_mcp/
│       ├── __init__.py
│       └── server.py          # Main MCP server implementation
├── tests/
│   └── test_server.py         # Automated tests (simulated ADS, no token needed)
├── test_connection.py         # Manual check against the real ADS API
├── .env.example               # Template for API token
├── .gitignore
├── pyproject.toml             # Project configuration
├── CHANGELOG.md
├── ROADMAP.md                 # Plans, known issues, and the release process
├── CITATION.cff               # How to cite this software
├── README.md
└── LICENSE

Testing

The automated tests simulate ADS responses, so they need no token or network. Run uv sync first: it installs pytest along with the other development tools (if uv run pytest says "No such file or directory", this step is missing, or uv needs updating with uv self update).

uv sync
uv run pytest

To check that your token works against the real ADS API (read-only calls):

uv run python test_connection.py

Contributing

Contributions are welcome! ROADMAP.md lists what's planned next, the known issues, and how releases work.

Technical Details

Built with:

• MCP SDK (Python, 2.x) for the MCP protocol: each tool is a typed Python function, and its input schema comes from the type hints
• httpx for asynchronous calls to the ADS API (search, export, metrics, libraries)
• python-dotenv for secure token management

The server uses:

• stdio transport to talk to Claude Desktop and Claude Code
• The ADS export service for BibTeX, so entries match what ADS itself exports
• Tool annotations that tell Claude which tools only read and which change your ADS libraries
• Rate limiting handled by NASA ADS API (the server reports when the limit is reached)

Known Limitations

• Rate limits: NASA ADS enforces rate limits. Monitor your usage for large queries.
• Author name matching: author searches and metrics match every paper with that name, so common names can include other people's papers.
• Author metrics: use at most the first 2000 papers found (the server says so when this happens).

Troubleshooting

Server won't start

1. Verify uv is on your PATH: uv --version (it fetches the Python version pinned in .python-version itself)
2. Check API token is in .env file
3. Ensure uv sync completed successfully
4. Check Claude Desktop logs in Settings > Developer
5. To keep a log file of your own, set NASA_ADS_LOG_FILE=/path/to/nasa-ads-mcp.log in .env

Executable not found in $PATH: "uv"

uv isn't installed, or Claude Code started before it was. Install uv (see Prerequisites), then restart Claude Code (or Claude Desktop) so it sees the new PATH.

"Failed to connect" or "connection timed out" on the first start

The first start downloads Python and the dependencies, which can take longer than the 30 seconds Claude Code waits. Wait a minute, then run /reload-plugins or start a new session.

Python download crawls (institutional networks)

On some networks, uv python install (and the first start) slows to a few KB/s while a direct download from GitHub runs at full speed. Point uv at GitHub directly, once:

UV_PYTHON_INSTALL_MIRROR=https://github.com/astral-sh/python-build-standalone/releases/download uv python install 3.13

uv then reuses this Python, so the plugin's start needs no download.

API errors

1. Verify your ADS API token is valid
2. Check you haven't hit rate limits
3. Confirm bibcodes are correctly formatted (19 characters, padded with dots). Lookups also accept DOIs, arXiv IDs and a paper's earlier bibcodes

Can't see tools in Claude

1. Fully quit and restart Claude Desktop
2. Check that nasa-ads is listed under Settings > Developer (Claude Desktop) or in /mcp (Claude Code)
3. Verify config path is absolute, not relative

Data and Privacy

This server runs on your own computer. It sends your search queries, bibcodes, and library requests only to the NASA ADS API (api.adsabs.harvard.edu), authenticated with your own ADS token. It stores no data of its own and sends nothing anywhere else. Your token stays in your local .env file. What ADS does with API requests is covered by the ADS privacy policy.

Icon

The icon is the logo of the Pleiad Astronomy group, designed by Ingrid Beloto, in light- and dark-theme versions made in the group's visual-identity repository. The MIT license covers this project's code and documentation, not the logo: the files in assets/ belong to the Pleiad group.

Related Projects

Other MCP servers for ADS that we know of. Suggestions for this list are welcome.

• scix-mcp: the official server from the ADS/SciX team (TypeScript, npx scix-mcp). Broad API coverage, including citation networks, 23 export formats, and library sharing and annotations. First released on npm on 2025-11-20.
• mcp-server-ads by cbyrohl (Python, uvx). Includes object-name resolution, reference-string resolution, and citation/collaboration networks.

This project was first released on 2025-11-02. When we built it, we searched for an existing ADS MCP server and found none, so it was developed independently. We're glad the ADS team now offers an official one.

Acknowledgments

• NASA Astrophysics Data System for providing the API
• Anthropic for creating MCP and Claude
• Astronomy community for maintaining the world's best literature database

How This Was Made

This server is a human–AI collaboration. Claude (Anthropic) wrote 100% of the code and documentation; Paula Coelho did not change a single comma of the code. Paula brought the idea, the astronomy and ADS knowledge, the requirements, the testing in real research, and every decision about what the tool should be. It would not exist without both: in Paula's words, it is not something she would have pursued alone.Credit is shared. Accountability is Paula's, she carries it in the name of the collaboration.

Contributions, using the CRediT roles:

• Paula Coelho: Conceptualization, Methodology (astronomy and ADS knowledge), Validation, Supervision, Project administration
• Claude (Anthropic): Software, Writing – original draft

The git history records Claude's part in each change through Co-Authored-By lines. "Claude (Anthropic)" is listed as a collective author, much as software papers credit "The Astropy Collaboration": several Claude instances and model versions contributed over time.

Citation

If you use this tool in your research workflow, you can cite it as below. GitHub's "Cite this repository" button reads the same information from CITATION.cff.

@software{nasa_ads_mcp,
  author = {Coelho, Paula and {Claude (Anthropic)}},
  title = {NASA ADS MCP Server},
  note = {Human--AI collaboration; maintained by Paula Coelho},
  version = {0.2.0},
  year = {2025},
  url = {https://github.com/prtc/nasa-ads-mcp}
}

If you write about using this tool in a journal article, follow the journal's policy on AI: most don't accept AI as an author, so the collaboration belongs in the AI-use disclosure or acknowledgments.

License

MIT License - see LICENSE file for details.

---

Questions or Issues? Open an issue on GitHub or contact through the repository.

Want to learn more about MCP? Visit modelcontextprotocol.io