# quasar-mcp

[![CI](https://github.com/adamzacharia/quasar-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/adamzacharia/quasar-mcp/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://github.com/adamzacharia/quasar-mcp/blob/main/pyproject.toml)
[![Tools](https://img.shields.io/badge/tools-198-informational.svg)](https://github.com/adamzacharia/quasar-mcp/blob/main/docs/TOOLS.md)
[![License: PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm%20Noncommercial-orange.svg)](https://github.com/adamzacharia/quasar-mcp/blob/main/LICENSE)

**quasar-mcp** is an [MCP](https://modelcontextprotocol.io) server that gives LLM clients such as Claude Code,
Claude Desktop, Codex and Cursor the research tools of [Quasar](https://github.com/adamzacharia/Quasar), an AI
research assistant for astronomy archive workflows. It serves about 200 tools, all working on live data:

| Area | What the tools do |
|---|---|
| **ALMA and NRAO** | search the ALMA Science Archive by target, position, frequency or exact line coverage; per-project census; per-source summaries; QA2 status; file inventories; downloads; CASA imaging scripts; curated query recipes |
| **Other archives** | MAST (JWST, HST, TESS, Kepler), ESO, CADC, HEASARC, IRSA, Gaia DR3, NASA Exoplanet Archive, ATNF pulsars, TNS, GWOSC |
| **Virtual Observatory** | find TAP, SIA and cone services in the IVOA registry; list and describe tables; run guarded ADQL; image search; MOC coverage algebra |
| **Catalogues** | SIMBAD, NED, VizieR; positional cross-matching; Galactic extinction; Bailer-Jones distances |
| **Spectral lines** | Splatalogue: identify a frequency, survey a range, search by molecule |
| **Literature** | NASA ADS search with exact counts, BibTeX, citations, author metrics, the ALMA bibliography, methods extraction from papers |
| **NOIRLab Astro Data Lab** | governed catalogue queries, colour-magnitude diagrams, density maps, cutouts, dwarf-satellite and stream searches, light curves |
| **Time domain** | ZTF/ALeRCE alerts, stamps and light curves; TESS/Kepler light curves; period search; variability statistics |
| **Images and analysis** | HiPS cutouts and RGB composites, finding charts, contour overlays, moment maps, PV slices, source detection, photometry, SEDs |
| **Calculators** | ALMA sensitivity (Technical Handbook radiometer equation), beam size, Doppler conversions, cosmology, coordinates |

Plots and images are returned as MCP image content, so clients that display images show them inline. The full
reference for every tool and its parameters is in **[docs/TOOLS.md](docs/TOOLS.md)**.

## Installation

Python 3.12 or later. The recommended way is [uv](https://docs.astral.sh/uv/), which runs the server in its own
environment without a separate install step:

```bash
uvx --from git+https://github.com/adamzacharia/quasar-mcp quasar-mcp --list
```

The first run installs the scientific Python stack (astropy, astroquery, pyvo and friends) and takes a few
minutes; later starts take 10 to 25 seconds. Run that command once in a terminal before adding the server to a
client with a short startup timeout. It prints the tool list when it is ready.

Or install it with pip into an environment of your choice:

```bash
pip install git+https://github.com/adamzacharia/quasar-mcp
quasar-mcp --list
```

## Connect a client

**Claude Code**

```bash
claude mcp add quasar -- uvx --from git+https://github.com/adamzacharia/quasar-mcp quasar-mcp
```

**Claude Desktop** (Settings > Developer > Edit Config), **Cursor** (`~/.cursor/mcp.json`) or any client with a JSON
config:

```json
{
  "mcpServers": {
    "quasar": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/adamzacharia/quasar-mcp", "quasar-mcp"]
    }
  }
}
```

**Codex** (`~/.codex/config.toml`):

```toml
[mcp_servers.quasar]
command = "uvx"
args = ["--from", "git+https://github.com/adamzacharia/quasar-mcp", "quasar-mcp"]
```

If you installed with pip, use `quasar-mcp` as the command with no arguments.

Then ask, for example:

- *Which ALMA Band 7 observations of TW Hya have resolution better than 0.1 arcsec?*
- *What lines lie within 50 MHz of CO 3-2?*
- *Give me the BibTeX for the DSHARP overview paper.*
- *Make a finding chart for HL Tau and list Gaia DR3 stars within 1 arcmin.*

### Serving a subset

Every tool description is sent to the model. Clients that load all tools up front can be given a subset:

```bash
quasar-mcp --categories archive,literature
```

Categories: `general` (ALMA archive, lines, MAST/ESO/CADC, web), `archive` (archives, catalogues, VO),
`literature`, `datalab`, `analysis`, `mmu_hats`. Claude Code loads tool descriptions on demand, so it does not need
this.

## Configuration

Most tools use public services and need no configuration. API keys for the rest are read from environment
variables or from `~/.quasar-mcp/.env` (copy [`.env.example`](.env.example) there); a real environment variable
wins over the file.

| Variable | Unlocks |
|---|---|
| `NASA_ADS_API_KEY` | ADS search, BibTeX, citations, author metrics ([free token](https://ui.adsabs.harvard.edu/user/settings/token)) |
| `TAVILY_API_KEY`, `EXA_API_KEY` | web search, extract and research tools |
| `DATALAB_TOKEN` | long Data Lab queries as server-side jobs (queries work anonymously without it) |
| `QDRANT_URL`, `QDRANT_API_KEY`, `OPENAI_API_KEY` | documentation passages in `alma_reference` (its reference tables work without them) |
| `QUASAR_MCP_HOME` | folder for `.env`, downloads and caches (default `~/.quasar-mcp`) |

A tool whose key is missing returns an error that names the variable; every other tool keeps working. Keys can
also be passed in the client config:

```json
"quasar": {"command": "uvx", "args": ["--from", "git+https://github.com/adamzacharia/quasar-mcp", "quasar-mcp"],
           "env": {"NASA_ADS_API_KEY": "your-token"}}
```

### Shared HTTP server

```bash
quasar-mcp --http 8765                 # streamable HTTP at http://127.0.0.1:8765/mcp
claude mcp add --transport http quasar http://127.0.0.1:8765/mcp
```

The HTTP server has no authentication, spends the API keys it was started with, and can download files to its
machine. Keep the default `127.0.0.1` binding and put an authenticating proxy or VPN in front before sharing it.
All HTTP clients share one session.

## Behaviour worth knowing

- **Tools can build on the previous search.** `filter_results`, `check_line_coverage`, `check_co_lines`,
  `plot_alma_results` and `get_mast_products` work on the last archive search in the same session.
- **Results carry their provenance.** Archive tools report the query or ADQL they ran and the service they hit, and
  every tool has a time budget; a slow or failed service returns a structured error naming the host instead of
  hanging. Models usually recover with another tool (for example `resolve_target` falls back from SIMBAD to
  Sesame).
- **No invented data.** When a service or key is unavailable the tool says so; it never substitutes examples.
- **Downloads** go to the machine running the server: ALMA products under `~/.quasar-mcp/downloads/`, MAST
  products under `~/quasar_data/mast/`.
- Not included from Quasar: the chat app, web interface, accounts and the server-side browser tools.

## Tested

Before each release the server is started as a real MCP client would start it and driven by language models on
realistic questions (ALMA archive counts, line identification, BibTeX, the GWOSC catalogue, sensitivity), with
every number checked against the tool's own output. For 0.1.0, on a fresh install:

| Client | Result |
|---|---|
| Claude Code (Claude Sonnet) | 4 / 5; the miss was the model choosing its own weather (PWV), not a tool error |
| gpt-oss-120b (open model, via an OpenAI-compatible API) | 5 / 5 |

## Development

```bash
git clone https://github.com/adamzacharia/quasar-mcp
cd quasar-mcp
python -m venv .venv && . .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -e ".[test]"
pytest                                            # unit tests + a full server start
python scripts/gen_tools_doc.py                   # regenerate docs/TOOLS.md
```

The tools themselves are developed in the [Quasar repository](https://github.com/adamzacharia/Quasar).
`src/quasar_mcp/_vendor/` is a copy of Quasar's backend, refreshed with
`python scripts/sync_from_quasar.py /path/to/Quasar` (it scans the copy for keys and local paths before finishing);
[`UPSTREAM.md`](UPSTREAM.md) records the Quasar commit. Report tool bugs and requests in
[issues](https://github.com/adamzacharia/quasar-mcp/issues).

## Related

- [alma-mcp](https://github.com/adamzacharia/alma-mcp): MCP servers with methods, settings and recipes from about
  3,500 ALMA papers, plus tested analysis tools (dust masses, line luminosities, kinematics, uv fitting). It pairs
  with this server: alma-mcp says how published papers did a step, quasar-mcp fetches the data to do it.

## License

[PolyForm Noncommercial 1.0.0](LICENSE): free for research, teaching and other noncommercial use. The ALMA guidance
reference in `src/quasar_mcp/_vendor/third_party/alma-data-skill/` is included with its author's permission (see
its `UPSTREAM.json`).