# 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](docs/student-guide.md) or [Portuguese](docs/guia-do-estudante.md).

### Prerequisites

- **uv**, the Python package manager, which also fetches Python for you if needed ([install instructions](https://docs.astral.sh/uv/getting-started/installation/)). On Linux and macOS:
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
- **A NASA ADS API token**, free with an ADS account ([get yours here](https://ui.adsabs.harvard.edu/user/settings/token))

### 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](#option-1-claude-code-plugin-recommended) |
| Claude Desktop chat (macOS, Windows, Linux beta) | ✅ | [Option 2: one-click bundle](#option-2-claude-desktop-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):
   ```bash
   claude plugin marketplace add prtc/nasa-ads-mcp
   ```
2. **Install the plugin:**
   ```bash
   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 takes a few extra seconds while uv installs the server's dependencies.

**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:

```json
{
  "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](https://claude.com/docs/plugins/org-sync).

### Option 2: Claude Desktop (one-click bundle)

1. Download [`nasa-ads.mcpb`](https://github.com/prtc/nasa-ads-mcp/releases/latest/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:**
```bash
git clone https://github.com/prtc/nasa-ads-mcp.git
cd nasa-ads-mcp
```

2. **Install dependencies:**
```bash
uv sync
```

3. **Configure your API token:**

Create a `.env` file in the project root:
```bash
cp .env.example .env
```

Edit `.env` and add your NASA ADS API token:
```
ADS_API_TOKEN=your_token_here
```

4. **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:
```json
{
  "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.

5. **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`).
```bash
uv sync
uv run pytest
```

To check that your token works against the real ADS API (read-only calls):
```bash
uv run python test_connection.py
```

### Contributing

Contributions are welcome! [ROADMAP.md](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 Python 3.10+ is installed: `python3 --version`
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`

### 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](https://ui.adsabs.harvard.edu/help/policies/privacy).

## Icon

The icon is the logo of the [Pleiad Astronomy](https://pleiad-astronomy.github.io) group, **designed by Ingrid Beloto**, in light- and dark-theme versions made in the group's [visual-identity](https://github.com/pleiad-astronomy/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](https://github.com/adsabs/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](https://github.com/cbyrohl/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](https://credit.niso.org/) 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`](CITATION.cff).
```bibtex
@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](https://modelcontextprotocol.io)