Skip to main content
Glama

AstroMCP

CI PyPI Python License: MIT

The PyPI package is astro-checker (the name astromcp is too close to an unrelated existing package). The project is still called AstroMCP and both astro-checker and astromcp commands are installed.

An MCP server that gives AI assistants (Claude, Cursor, VS Code, ...) direct, read-only access to public astronomy archives, so you can check a sky position in seconds and answer the first question of any discovery: is it already known?

It queries the Transient Name Server (TNS), SIMBAD, AAVSO VSX, Gaia DR3, ExoFOP-TESS, ALeRCE/ZTF, Fink/Rubin (LSST), IMCCE SkyBoT and several image surveys, and returns compact JSON the model can reason about.

Note: answers depend on third-party services. Archives go down, rate-limit, or lag behind reality (for example, the public TNS archive is refreshed once a day). AstroMCP reports failed sources explicitly instead of pretending nothing is there, but always confirm important results at the source before reporting a discovery.

Tools (14)

Tool

What it does

whats_here(ra, dec, radius_arcsec=5, epoch=None)

Queries all archives in parallel and returns a verdict (known transient, known TESS object of interest, known variable, known asteroid, star, known object, nothing known) with evidence, failed sources and image links

tns_object(name)

Looks up a transient on TNS by name (e.g. 2026agtq)

tns_search(ra, dec, radius_arcsec=5)

TNS cone search

ztf_lightcurve(oid)

ZTF light curve from ALeRCE (detections with magpsf/magpsf_corr, non-detection summary)

ztf_objects_near(ra, dec, radius_arcsec=5)

ZTF alert objects near a position (ALeRCE)

rubin_object(dia_object_id)

Rubin/LSST object light curve and cutouts (Fink)

rubin_recent(tag="most_likely_sn", days=3)

Recent Rubin objects in a Fink classification tag

simbad(ra, dec, radius_arcsec=10)

SIMBAD cone search (TAP)

vsx(ra, dec, radius_arcsec=10)

AAVSO VSX variable-star cone search

gaia(ra, dec, radius_arcsec=5)

Gaia DR3 sources (via VizieR)

tess_known(tic=None, ra=None, dec=None)

TESS TOIs, CTOIs and eclipsing binaries (ExoFOP-TESS, VizieR, TIC v8.2)

asteroids_at(ra, dec, epoch_iso, radius_arcsec=30)

Known solar-system objects at a position and time (IMCCE SkyBoT)

cutout_urls(ra, dec, size_arcsec=60)

Image links: Legacy Survey DR10, Pan-STARRS, DSS2, Aladin

observe_tonight(lat, lon, ...)

Bright, recent, still-unclassified TNS transients observable from your site tonight, ranked

Coordinates are ICRS decimal degrees; times are ISO 8601 UTC. Errors come back as {"error": "..."} and, in whats_here, as sources_failed plus a caveat, so a missing archive is never mistaken for "nothing known".

Related MCP server: Trillian MCP

Examples

These are real checks (also in tests/test_integration.py):

"Is there anything known at RA 40.22898, Dec +12.601026?"

whats_here(40.22898, 12.601026)
→ verdict: "known transient"
  evidence: ["TNS: AT 2026agtq at 0.0\"", "ZTF: ZTF26acatcla ndet=10 class=None"]

"What is at the position of TOI-2330?"

whats_here(172.85872, -41.68953)
→ verdict: "known TESS object of interest"
  labels: ["known TESS object of interest", "known variable", "star"]
  evidence: ["SIMBAD: WASP-128 [*] at 0.01\"", "SIMBAD: WASP-128b [BD?] at 0.01\"", "VSX: WASP-128 (EA/BD+ROT) at 0.04\"", ...]

The assistant can then answer: "That's TOI-2330, already known as WASP-128 b, a brown dwarf transiting WASP-128."

An empty patch of sky:

whats_here(200.5, -20.3, 3)
→ verdict: "nothing known", sources_failed: []

"What should I observe tonight from Curitiba?"

observe_tonight(lat=-25.43, lon=-49.27)
→ night_utc: ["2026-10-26T22:27Z", "2026-10-27T07:37Z"], moon illumination 0.99, 33 matching targets
  1. AT 2026afvp  mag 10.3, 8.1 d old, max alt 40.9°, window 03:57–07:37 UTC
  2. AT 2026agsu  mag 17.27, 2.2 d old, max alt 82.8°, window 22:27–02:37 UTC
  ...

observe_tonight selects transients up to 21 days old, TNS discovery mag ≤ 18.5, still unclassified, above 30° while the Sun is below −12° and at least 20° from the Moon (all adjustable). Sun/Moon positions use the Astronomical Almanac low-precision formulas (arcminute level). It is meant to help small telescopes and spectroscopy groups pick classification targets.

Install

Requires Python 3.11+.

uvx astro-checker       # run without installing (recommended; needs uv)
pip install astro-checker  # or install into an environment, then run `astro-checker` (alias: `astromcp`)

Or with Docker (from a clone): docker build -t astromcp . && docker run -i --rm astromcp. See .env.example for the optional variables.

The server speaks MCP over stdio; you normally don't run it by hand, your MCP client launches it.

Configure your MCP client

Claude Code

claude mcp add astromcp -- uvx astro-checker
# with TNS credentials:
claude mcp add astromcp -e TNS_BOT_ID=12345 -e TNS_BOT_NAME=my_bot -e TNS_API_KEY=... -- uvx astro-checker

Add --scope user to make it available in every project.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/; Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "astromcp": {
      "command": "uvx",
      "args": ["astromcp"],
      "env": { "TNS_BOT_ID": "12345", "TNS_BOT_NAME": "my_bot", "TNS_API_KEY": "..." }
    }
  }
}

The env block is optional.

Other clients (Cursor, VS Code, Zed, Continue, ...)

Any client that launches stdio MCP servers works with command uvx and args ["astromcp"], or command astromcp if you installed it with pip. Try it interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector uvx astro-checker

Environment variables

Variable

Default

Meaning

TNS_BOT_ID, TNS_BOT_NAME, TNS_API_KEY

unset

Optional TNS bot credentials (create a bot) for live TNS queries

TNS_PUBLIC_CSV

unset

Path to a downloaded tns_public_objects.csv.zip, used when there are no credentials

ASTROMCP_CACHE_DIR

~/.cache/astromcp

Disk cache (HTTP responses for minutes to hours; ExoFOP tables 12 h; TNS archive 20 h)

Without TNS credentials, TNS answers come from the daily public objects archive (cached copy or TNS_PUBLIC_CSV); objects reported since 00:00 UTC are missing from it, and whats_here flags this instead of returning a clean "nothing known". The API key is never returned in responses, written to logs, or stored in the cache.

Rate limits and good citizenship

These archives are free public services run by small teams. AstroMCP is built to be polite:

  • TNS cone searches are serialized and spaced 6.5 s apart (TNS allows 10 per minute); Retry-After is honored on HTTP 429.

  • Every request has a timeout, retries with backoff, and a per-host circuit breaker: when a host fails repeatedly it is skipped for two minutes instead of stalling every query.

  • Large tables (ExoFOP TOI/CTOI, TNS public archive) are downloaded once and cached on disk.

Please do the same: don't run whats_here over thousands of positions in a loop (use the archives' bulk services for that), keep your own TNS bot for live queries, and credit the archives in publications (TNS, SIMBAD/CDS, AAVSO VSX, ESA Gaia, ExoFOP-TESS, ALeRCE, Fink, IMCCE, Legacy Survey, Pan-STARRS).

Development

git clone https://github.com/louisperner/AstroMCP && cd AstroMCP
uv sync
uv run pytest                      # offline tests (recorded responses in tests/fixtures)
uv run pytest -m integration       # live queries against the real archives (TNS test needs credentials)
uv run ruff check . && uv run ruff format --check . && uv run mypy --strict

See CONTRIBUTING.md and CHANGELOG.md.

Publishing to the MCP Registry (maintainers)

server.json describes the PyPI package for the official MCP Registry. After the version is on PyPI (the mcp-name comment above must be in the published README):

brew install mcp-publisher        # or download a release binary
mcp-publisher login github        # authenticates the io.github.louisperner namespace
mcp-publisher publish             # reads ./server.json

Bump version in pyproject.toml, src/astromcp/__init__.py and both places in server.json together.

Em português

O AstroMCP é um servidor MCP que dá a assistentes de IA acesso direto (somente leitura) a bases públicas de astronomia — TNS, SIMBAD, VSX, Gaia DR3, ExoFOP-TESS, ALeRCE/ZTF, Fink/Rubin, SkyBoT e cutouts de imagem — para verificar rapidamente se um objeto já é conhecido. Comece por whats_here(ra, dec); para planejar a noite, observe_tonight(lat, lon). Instale com uvx astro-checker ou pip install astro-checker e, no Claude Code, claude mcp add astromcp -- uvx astro-checker. Credenciais do bot do TNS (opcionais) vão nas variáveis TNS_BOT_ID, TNS_BOT_NAME e TNS_API_KEY e nunca aparecem nas respostas. As respostas dependem de serviços externos: confirme na fonte antes de anunciar uma descoberta.

License

MIT © 2026 Louis Perner

Available Tools

14 tools
asteroids_atB
Read-onlyIdempotent

Known solar-system objects near a position at a given time (IMCCE SkyBoT, geocentric): name, class, V mag, separation, motion. epoch_iso is UTC, e.g. '2026-10-20T03:15:00'.

Inputs: ra (required), dec (required), epoch_iso (required), radius_arcsec. Returns: object

cutout_urlsB
Read-onlyIdempotent

Image cutout links for a position: Legacy Survey DR10 (JPEG/FITS/viewer), Pan-STARRS color, DSS2 red and Aladin Lite.

Inputs: ra (required), dec (required), size_arcsec. Returns: object

gaiaA
Read-onlyIdempotent

Gaia DR3 sources within radius, nearest first: G, BP-RP, parallax (+S/N), proper motion, RUWE, variability flag, and a 'likely_star' flag (parallax S/N > 3 or PM > 5 mas/yr).

Inputs: ra (required), dec (required), radius_arcsec. Returns: object

observe_tonightA
Read-onlyIdempotent

What to observe tonight: recent (<= max_age_days), bright (TNS discovery mag <= mag_limit) transients that are still UNCLASSIFIED on TNS and observable from the site (lat/lon in degrees, east-positive longitude) during the night starting on the local evening of date (YYYY-MM-DD, default today UTC): above min_altitude while the Sun is below -12 deg and at least min_moon_sep from the Moon. Ranked by priority (brighter, younger, longer window). Use it to plan follow-up photometry or spectroscopic classification. Returns night window, Moon illumination and targets with max altitude, transit time, observing window and TNS link.

Inputs: lat (required), lon (required), date, limit, +5 more. Returns: object

rubin_objectA
Read-onlyIdempotent

Rubin/LSST object from the Fink broker by diaObjectId: position, light curve (AB mag from nJy flux), and cutout links of the latest alert.

Inputs: dia_object_id (required). Returns: object

rubin_recentA
Read-onlyIdempotent

Recent Rubin objects in a Fink LSST tag over the last N days (max 30), brightest first. Tags: most_likely_sn, sn_near_galaxy_candidate, extragalactic_new_candidate, extragalactic_lt20mag_candidate, hostless_candidate.

Inputs: tag, days. Returns: object

simbadB
Read-onlyIdempotent

SIMBAD objects within radius (nearest first): main id, object type, spectral type, redshift.

Inputs: ra (required), dec (required), radius_arcsec. Returns: object

tess_knownB
Read-onlyIdempotent

Known TESS objects for a TIC id and/or position: TOIs and CTOIs (ExoFOP-TESS) and TESS eclipsing binaries (Prsa et al. 2022). With only a TIC, its position comes from TIC v8.2.

Inputs: ra, dec, tic, radius_arcsec. Returns: object

tns_objectA
Read-onlyIdempotent

Look up a Transient Name Server object by name, e.g. '2026agtq' or 'AT 2026agtq': position, type, redshift, discovery date/mag, reporting group, internal names.

Inputs: name (required). Returns: object

vsxB
Read-onlyIdempotent

AAVSO VSX variable stars within radius: name, variability type, range, period.

Inputs: ra (required), dec (required), radius_arcsec. Returns: object

whats_hereA
Read-onlyIdempotent

Is it already known? Query TNS, SIMBAD, VSX, Gaia DR3, ExoFOP TOI/CTOI, ZTF (ALeRCE) and, if epoch (ISO UTC, e.g. '2026-10-20T03:15:00') is given, known asteroids (SkyBoT), all in parallel. Returns a verdict (the most specific of: 'known transient', 'known TESS object of interest', 'known variable', 'known asteroid', 'star', 'known ZTF alert source', 'known object', 'nothing known'), all matching labels, one-line evidence per hit, which sources failed, per-source details and image cutout links. ra/dec in decimal degrees (ICRS).

Inputs: ra (required), dec (required), epoch, radius_arcsec. Returns: object

ztf_lightcurveA
Read-onlyIdempotent

ZTF light curve from ALeRCE for an object id like 'ZTF26acatcla': per-band summary, detections (magpsf and magpsf_corr) and non-detection summary (last limit before first detection).

Inputs: oid (required). Returns: object

ztf_objects_nearC
Read-onlyIdempotent

ZTF objects (ALeRCE) within radius of a position.

Inputs: ra (required), dec (required), radius_arcsec. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools have distinct resource-and-action purposes: TNS name lookup vs. cone search, ZTF light curve vs. nearby objects, Rubin object vs. recent objects. The main ambiguity is that whats_here aggregates SIMBAD, VSX, Gaia, TESS, ZTF, and asteroid lookups while individual catalog tools also exist, so an agent must decide between broad and targeted queries. Descriptions largely resolve this, but the overlap keeps it from a 5.

    Naming Consistency3/5

    Names are readable and often grouped by resource prefix (tns_object, ztf_lightcurve, rubin_recent), but conventions are mixed: bare catalog names like simbad, vsx, and gaia, verb-style observe_tonight, and noun/qualifier forms like tess_known and asteroids_at. There is no single predictable action pattern throughout.

    Tool Count5/5

    Fourteen tools is well within the ideal range and each maps to a meaningful astronomy follow-up capability. The set covers several catalogs, planning, cutouts, and transient brokers without obvious redundancy at the count level.

    Completeness4/5

    The surface covers a broad range of object lookup, crossmatching, transient discovery, and observing-planning needs across TESS, SIMBAD, VSX, Gaia, TNS, ZTF, and Rubin. Minor gaps remain, such as a general name-to-coordinate resolver or NED/MPC catalog access, but core workflows are supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Accurate astronomical catalog data and observing session planner for LLM assistants. Stops hallucinated magnitudes, coordinates, and visibility.
      3
      123 npm
      3
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language queries of astronomical data across multiple archives (Gaia, 2MASS, image holdings) via the Trillian platform, allowing users to search catalogs and find images by sky coordinates.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to query NASA/JPL data on asteroids and comets, including small-body orbits and physical parameters, near-Earth close approaches, Sentry impact-risk assessments, and recent atmospheric fireballs. All four tools are keyless and work over a hosted gateway endpoint or a local stdio server.
      89 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Connects AI assistants to Vetstar, MAST, SIMBAD, VizieR, Gaia DR3, ExoFOP-TESS, the NASA Exoplanet Archive, NASA ADS, Crossref/DataCite, the UAT, and Zenodo so users can vet TESS candidates, fit ephemerides, check contamination and novelty, build RNAAS manuscripts, verify references, and prepare Zenodo submission bundles. It prepares analyses and files only, leaving uploads, submissions, and publishing to the user.
      1
      MIT