Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@AstroMCP Is anything already known at RA 40.22898, Dec +12.601026?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The PyPI package is
astro-checker(the nameastromcpis too close to an unrelated existing package). The project is still called AstroMCP and bothastro-checkerandastromcpcommands 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.
Tool | What it does |
| Queries all archives in parallel and returns a verdict ( |
| Looks up a transient on TNS by name (e.g. |
| TNS cone search |
| ZTF light curve from ALeRCE (detections with |
| ZTF alert objects near a position (ALeRCE) |
| Rubin/LSST object light curve and cutouts (Fink) |
| Recent Rubin objects in a Fink classification tag |
| SIMBAD cone search (TAP) |
| AAVSO VSX variable-star cone search |
| Gaia DR3 sources (via VizieR) |
| TESS TOIs, CTOIs and eclipsing binaries (ExoFOP-TESS, VizieR, TIC v8.2) |
| Known solar-system objects at a position and time (IMCCE SkyBoT) |
| Image links: Legacy Survey DR10, Pan-STARRS, DSS2, Aladin |
| 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: aqc-mcp
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.
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.
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-checkerAdd --scope user to make it available in every project.
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.
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-checkerVariable | Default | Meaning |
| unset | Optional TNS bot credentials (create a bot) for live TNS queries |
| unset | Path to a downloaded |
|
| 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.
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).
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 --strictSee CONTRIBUTING.md and CHANGELOG.md.
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.jsonBump version in pyproject.toml, src/astromcp/__init__.py and both places in server.json together.
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.
MIT © 2026 Louis Perner
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
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
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
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/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
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
SIMBAD objects within radius (nearest first): main id, object type, spectral type, redshift.
Inputs: ra (required), dec (required), radius_arcsec. Returns: object
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
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
Transient Name Server cone search (live API if bot credentials are set, rate-limited to 10/min; otherwise the cached daily public archive).
Inputs: ra (required), dec (required), radius_arcsec. Returns: object
AAVSO VSX variable stars within radius: name, variability type, range, period.
Inputs: ra (required), dec (required), radius_arcsec. Returns: object
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 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 (ALeRCE) within radius of a position.
Inputs: ra (required), dec (required), radius_arcsec. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 14 tools
Most tools target a clearly distinct source+action pair (vsx, simbad, gaia, tess_known, asteroids_at, cutout_urls, observe_tonight), so misselection is unlikely for the bulk of the set. The main overlap is `whats_here`, which fans out to TNS, SIMBAD, VSX, Gaia, ExoFOP and ZTF in parallel and therefore duplicates the individual per-survey tools; descriptions hint at the verdict-vs-detail distinction but do not state a hard rule for when to use the aggregator versus the specialists.
All names are lowercase snake_case with a predictable source-prefix convention: bare survey names for cone searches (vsx, simbad, gaia), `{survey}_{noun}` for targeted lookups (tns_object, ztf_lightcurve, rubin_recent, tess_known, asteroids_at), plus a few action-style names (whats_here, observe_tonight, cutout_urls). Verb-first naming is not universal, but the patterns are internally coherent and readable.
14 tools sit comfortably in the well-scoped range for a multi-survey astronomy cross-match server. Each tool maps to a distinct data source or workflow step (transient lookup, stellar cross-match, solar-system check, cutouts, observing planner) rather than padding the surface.
The discovery-vetting lifecycle is well covered: cross-match known catalogues, pull light curves and alerts from ZTF and Rubin, get cutouts, and plan follow-up with observe_tonight. Minor gaps remain — SIMBAD/Gaia are cone-search only with no name-based object detail, TNS objects have no light-curve retrieval, and there is no target-specific visibility/ephemeris tool separate from the nightly planner, but agents can work around these.
Read-only search of 2,189 AI agent tools (MCP servers, x402 APIs) with daily automated trust scores.
Factual sky for AIs: ISS, auroras, archives. Never confuses unexplained with extraterrestrial.
Public AI web-readiness scanner and machine-facing observability discovery service.
Observational astronomy in one place
