# 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 11 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`; searches the astronomy collection by default, and names the most cited papers that filter left out
- **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; suggests the ORCID iDs recorded on the name's first-author papers

### 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
- **check_references** - Check a manuscript's bibliography against ADS: finds each reference's bibcode, flags typos and wrong matches (first author, year, page), and lists what ADS can't find
- **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
  ```
  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](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 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:
```json
"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`, `check_references`, `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:

```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.

This entry belongs to the computer it's written on: the path exists only there. If you also use Claude Code on another machine (a remote host over SSH, say), install the plugin there instead (Option 1). The Claude desktop app can pass this entry on to a session on the other machine, where it fails with `No such file or directory (os error 2)`; see [Troubleshooting](#error-no-such-file-or-directory-os-error-2). Once the plugin is installed wherever you use Claude Code, consider removing this entry, so Claude doesn't see the server twice. (Whether the desktop app also passes the one-click bundle, Option 2, on to remote sessions hasn't been checked yet.)

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
```
"Check the references in my manuscript's bibliography against ADS: [paste the list]"
"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 `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`. It records each start (with the version and process ID) and each stop, so you can tell whether a "connecting" message in Claude meant the server really restarted. It holds about 1 MB, then starts over, keeping the previous one as `.log.1`, so it's safe to leave on

### `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:
```bash
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.

### `error: No such file or directory (os error 2)`
`uv` couldn't find the folder named after `--directory` in a manual entry (Option 3). uv doesn't say which path it tried. Usually the entry was written on another computer: the Claude desktop app can pass the entries in its `claude_desktop_config.json` to a Claude Code session on a remote host, where a path like `/Users/<you>/...` doesn't exist. The message then reads "Couldn't start on <host>" and "Added in the Claude desktop app on this computer". On the remote host, use the plugin (Option 1), and remove the manual entry from the desktop app's config, so the two don't compete. If the error appears on the computer that holds the clone, check that the path in the entry is absolute and still points at the clone.

### 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)