CASPER Astro Tools (casper-astro-tools)

Open astronomy tools for AI agents and scripts. The open, public part of CASPER, the assistant platform of CAMCEAD at the Institute of Astronomy, University of Cambridge.

46 read-only tools behind one calling protocol, usable as a Python library, a command line and a Model Context Protocol server (stdio and Streamable HTTP), with any model that can call functions:

The tool catalogue has one page per tool (description, input schema, example call, example output); docs/tools.json is the same in machine-readable form. Both are generated from the code and a test fails if they drift.

Also in this repository: a worked case study (plan a night at La Palma, check proper motions, find the key papers; runs offline), and CASPER AstroToolBench, a seed benchmark of 73 offline tasks with checkable answers for models that use these tools (bench/README.md).

Install

pip install casper-astro-tools        # from PyPI once released; until then: pip install .
casper-astro-tools doctor             # checks the installation (no network)

Python 3.10 or newer (tested on 3.11). Dependencies: astropy, numpy, scipy, httpx, defusedxml, mcp.

Use it

Python

import casper_astro_tools as at

at.call("astro_convert_coordinates", lon="18h36m56.3364s", lat="+38:47:01.291", to_frame="galactic")["output"]["l_deg"]   # 67.448...
at.call("astro_cosmology", redshifts=[0.5])["results"][0]["luminosity_distance_mpc"]                                      # Planck18
at.call("gaia_source", source_id="4472832130942575872")                                                                   # needs the network

Every call returns a dict: {"ok": true, ...} or {"ok": false, "error": "<code>", "message": "..."}. Inside a running event loop use await at.acall(...).

Command line

casper-astro-tools list                                     # the tools
casper-astro-tools describe astro_night_info                # schema and examples of one tool
casper-astro-tools call astro_night_info date=2026-11-12 site=wht
casper-astro-tools call resolve_name name="M 51" --offline  # answer from the bundled recordings, no network

MCP server (Claude Desktop, Claude Code, any MCP client)

casper-astro-tools serve                                    # stdio
casper-astro-tools serve --http --port 8765                 # Streamable HTTP at http://127.0.0.1:8765/mcp

{ "mcpServers": { "casper-astro-tools": { "command": "casper-astro-tools", "args": ["serve"], "env": { "ADS_API_TOKEN": "your-ads-token" } } } }

Every tool is annotated read-only; the literature and archive tools are marked "open world" (they contact a public service), the calculators are not.

Settings (environment variables, all optional)

What it does to be safe to give to a model

• Read-only. No tool writes, uploads, runs code or changes anything anywhere. ADQL queries must be a single SELECT (no comments, no semicolon, no write or sleep words outside quotes); TOP and MAXREC are forced to the row cap (500).
• Allow-listed hosts. The archive tools only contact hosts listed in src/casper_astro_tools/archives/services.py (https, port 443, no IP literals, every resolved address must be public; redirects are followed by hand and re-checked). A host found by a registry search is accepted for one hour in that process; no environment variable widens the list.
• Bounded. Row, byte, time and size caps on every call; arXiv is queued to one request per three seconds; ADS to 60 calls a minute.
• Untrusted data is labelled. Archive and literature results carry their provenance (service, address, query, time) and a notice that the content is third-party data, not instructions.
• Offline by construction. The calculators force astropy offline: nothing is downloaded, ever.

The HTTP server has no login: it binds to localhost. Put your own authenticating proxy in front before exposing it. See SECURITY.md.

Known limitations

• The hours-above-altitude figures count a 5-minute grid including both ends of the window, so they can exceed the true duration by one grid step (0.08 h).
• No dust map: astro_extinction_law takes E(B-V) from you. Cosmology distances ignore radiation (a 0.02 % effect at z = 0.5) and absolute_magnitude_no_k_correction has no K-correction by name.
• The Earth-orientation table is the one inside astropy; it is never refreshed over the network.
• Archive answers change when the archives do. The recordings under src/casper_astro_tools/data/fixtures are snapshots (archives 2026-10-22, arXiv and Gaia 2026-10-30), kept for tests and for the offline mode; the CDS services were unreachable from the recording host on 2026-10-30, so their snapshot is the older one.
• No ADS answer is recorded (ADS needs a personal token): the ADS examples in the catalogue come from an invented stand-in and say so on the page.

Tests, regenerating the docs

pip install -e .[test]
pytest                                   # no network; about 40 s
python tools/gen_catalogue.py            # regenerate docs/catalogue and docs/tools.json (the test suite fails if you forget)
python bench/make_tasks.py               # regenerate the benchmark task files
python tools/record_fixtures.py out.json # re-record the public-service answers (network; read-only)

Authors, citing, licence

Authors (all at the Institute of Astronomy, University of Cambridge; the first is the corresponding author): Alireza Molaeinezhad, Nicholas Walton, Marco Riello, Eduardo González Solares, Leigh Smith, Giuseppe D'Ago, David Homan.

Copyright 2026 CAMCEAD, Institute of Astronomy, University of Cambridge. Apache-2.0 (LICENSE, NOTICE). Please cite via CITATION.cff (GitHub and GitLab render it as "Cite this repository"); until a software DOI exists, cite as:

Molaeinezhad, A., Walton, N., Riello, M., González Solares, E., Smith, L., D'Ago, G., Homan, D. (2026). CASPER Astro Tools: open astronomy tools for AI agents and scripts (version 0.1.0) [Computer software]. Institute of Astronomy, University of Cambridge.

Security reports: see SECURITY.md.

Related work: ToolUniverse (an open platform of biomedical tools behind one protocol). This package is a small, astronomy-specific, read-only counterpart; see docs/DESIGN.md for how the two differ.

Acknowledgements

This package is a client of public services and of open software. If you publish results obtained with it, please acknowledge what you used; the full sentences, citations and terms are in docs/ACKNOWLEDGEMENTS.md (reviewed and accepted by the authors on 2026-11-01; where a service publishes different wording, use the service's). In short:

• This research has made use of the SIMBAD database, operated at CDS, Strasbourg, France. (Wenger et al. 2000, A&AS 143, 9)
• This research has made use of the VizieR catalogue access tool, CDS, Strasbourg, France (DOI: 10.26093/cds/vizier). (Ochsenbein et al. 2000, A&AS 143, 23)
• This research has made use of the NASA/IPAC Extragalactic Database (NED), which is funded by the National Aeronautics and Space Administration and operated by the California Institute of Technology.
• This work has made use of data from the European Space Agency (ESA) mission Gaia (https://www.cosmos.esa.int/gaia), processed by the Gaia Data Processing and Analysis Consortium (DPAC, https://www.cosmos.esa.int/web/gaia/dpac/consortium). (Gaia Collaboration 2016, 2023)
• This research has made use of NASA's Astrophysics Data System Bibliographic Services. ADS content is not redistributed by this package; the ADS examples are labelled stand-ins.
• This research made use of Astropy (http://www.astropy.org), a community-developed core Python package for Astronomy (Astropy Collaboration, 2013, 2018, 2022).
• arXiv: the API terms (one request per three seconds) are followed by the client; the arXiv metadata excerpts are shipped under arXiv's CC0 statement for metadata. Sesame, the CDS cross-match, hips2fits and the Virtual Observatory: see the acknowledgements page.

The short recorded excerpts of public answers under src/casper_astro_tools/data/fixtures each carry a mark naming the service and the date; see NOTICE.