Skip to main content
Glama

✦ SkyQuery

The sky, queryable. Your questions, real data, one conversation.

A free, local, open-source MCP server that puts the working astronomer's whole toolkit, object lookups, catalog cross-matches, ephemerides, literature, and observation planning, behind one conversational interface. Point any AI assistant at it and ask the sky anything. Runs entirely on your machine.

CI Python 3.12+ License: MIT Typed Built on astropy

Website · Developers · llms.txt · Install · The demo · How it works · Tools


The honest version, first

SkyQuery is a normalization and MCP layer on top of astroquery, which it credits loudly. It wraps free, publicly funded astronomy services (SIMBAD, JPL Horizons, VizieR, Gaia, ADS, and more), honors their rate limits, and attaches a citation to every value it returns. It is local-first: there is no SkyQuery server, nothing phones home, and your queries, keys, and downloaded data never leave your machine except to talk to those public services directly. You can read every line that touches the network.

It is not affiliated with NASA, JPL, CDS/Strasbourg, STScI, ESA, the Astropy project, or the unrelated JHU catalog tool of a similar name. It is not proprietary-data access, not telescope control, and not a hosted service. The answer to "can you host it for me" is "run it yourself, that is the point."

Related MCP server: aqc-mcp

Why it exists

The data is public and abundant. The interfaces are fragmented and unforgiving. To answer one ordinary question, "where is comet Apophis tonight, how big is it, and what's the latest paper on it?", you touch a JPL prompt, a SIMBAD form, and ADS query syntax, each with its own units and conventions, and you end up copying numbers between tabs by hand. Ask an LLM directly and it will happily invent an ephemeris that looks right and is wrong.

SkyQuery is the missing layer. It hands the assistant results that are typed, unit-tagged, and provenance-carrying instead of raw floats, so the model can reason over real data without guessing what "deg versus hourangle" or "J2000 versus ICRS" means.

The demo that sells it

"Where is asteroid Apophis on its 2029 approach, how big is it, and what's a paper about it?"

$ skyquery demo
99942 Apophis (2004 MN4)
  size: 0.34 km   H: 19.09 mag
  closest approach: 2029-Apr-13 22:00  0.000257245 AU  (0.100 lunar distances)
  visual magnitude at approach: 4.257 mag
  paper: Radar and Optical Observations of Near-Earth Asteroid 99942 Apophis (2024)

99942 Apophis (2004 MN4) is about 0.34 km. On 2029-Apr-13 22:00 it passes 0.000257 AU
from Earth (0.10 lunar distances), inside geostationary orbit. Source: JPL Horizons and SBDB.

JPL Horizons, the Small-Body Database, and the literature, answered in one breath, with the units, the frame, and the citation intact. That runs offline against shipped fixtures, so it works the moment you install it.

Install in under five minutes

# 1. Install (pick one)
uv tool install git+https://github.com/KarthikSubramanian07/skyquery   # recommended
pipx install git+https://github.com/KarthikSubramanian07/skyquery

# 2. Try it right now, offline, no keys
skyquery demo
skyquery resolve Vega
skyquery ephemeris "99942 Apophis" --start 2029-04-13 --stop 2029-04-14

Then point your assistant at it. Add one stdio block to your MCP client config (for example Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "skyquery": { "command": "skyquery-mcp" }
  }
}

That is the whole integration. SIMBAD, VizieR, and JPL Horizons need no key at all, so it is useful out of the box. Optional free keys unlock more, and go straight to your OS keychain, never a file:

skyquery login ads     # free ADS researcher token, unlocks literature
skyquery login nasa    # free NASA key, unlocks the APOD "wonder" layer

See SETUP.md for the exact steps and the --live flag.

How it works

  Your assistant  ──MCP──▶  SkyQuery  ──▶  SIMBAD · Horizons · VizieR · Gaia · ADS · ...
                           ◀── normalized + provenance ──

Every service response is parsed into one small set of typed models, Object, CatalogTable, Ephemeris, Paper, ObservationWindow, DataProduct, with values wrapped in astropy units and coordinates carried in explicit frames and epochs. One source of truth feeds both the MCP tools and the CLI.

  • One coordinate frame. Everything lands in ICRS degrees with its epoch explicit.

  • Every value sourced. Each field knows the service, the exact query, and the acknowledgment that service asks you to cite. Run skyquery cite for a ready-to-paste block.

  • Deterministic, not guessed. The correctness-critical logic (unit and frame conversion, cross-match, provenance) is pure and separated from I/O, and tested against known reference values.

  • A good citizen by construction. Human-scale rate limits and an on-disk cache are hard-coded floors, so a free service is never hammered.

The tool surface

The MCP server exposes normalized, well-documented tools an assistant can chain (resolve a name, get its ephemeris, find its papers):

Domain

Tools

Object intelligence

resolve_object, object_dossier

Ephemerides & small bodies

get_ephemeris, get_small_body, apophis_demo

Catalogs & cross-match

cone_search, crossmatch

Literature

search_literature

Analysis (no network)

convert_units, convert_frame, distance_from_parallax

Wonder layer

astronomy_picture_of_the_day

Provenance

session_citations

The CLI mirrors these: resolve, ephemeris, small-body, cone, literature, convert, frame, apod, demo, cite, plus setup, login, status. Every command takes --json for machine output and --live to leave replay mode and query the real services.

For the auditor

You should be able to verify the trust model from readable code and passing tests:

git clone https://github.com/KarthikSubramanian07/skyquery && cd skyquery
uv pip install -e ".[dev]"
pytest        # green with zero network and zero keys

The suite proves the three things that matter: numerical correctness (unit and frame conversions checked against astropy's own transforms and real captured reference values), good citizenship (the rate-limiter throttles bursts and backs off), and credential secrecy (keys touch only the keychain, and a test greps all log output to prove no token ever leaks). See DECISIONS.md for the architecture and the OSS ledger.

Built on the shoulders of

astropy · astroquery · astroplan · the Model Context Protocol SDK · and the free public services listed above. This tool is a thank-you note to all of them.

Support

SkyQuery is free forever and costs nothing to run. If it saved you a late-night tab-juggling session, you can buy me a coffee ☕.

License

MIT. Go build something with the sky.

Available Tools

13 tools
apophis_demoA

The headline demo: asteroid Apophis size, its 2029 close approach, a paper.

Answers "where is Apophis, how big is it, and what is the latest paper" in one call, combining SBDB, Horizons, and the literature with full provenance.

Inputs: with_paper. Returns: The headline demo answer: where is it, how big is it, latest paper.

astronomy_picture_of_the_dayA

Fetch NASA's Astronomy Picture of the Day (APOD) for a date, or today.

Works with the public DEMO_KEY out of the box; configure a free NASA key via skyquery login for higher rate limits.

Inputs: date. Returns: A normalized Astronomy Picture of the Day record.

convert_frameA

Transform coordinates between reference frames (ICRS, FK5, FK4, Galactic).

Uses astropy's tested transforms, never hand-rolled trigonometry. Returns the position in the target frame with the frame explicitly labeled.

Inputs: ra_deg (required), dec_deg (required), to_frame, from_frame. Returns: A position on the sky with an explicit reference frame. For equatorial frames (…

convert_unitsA

Convert a value between physical units with astropy's tested conversions.

Example: convert a parallax in mas, a distance in pc to ly, a velocity in km/s. Returns the converted value tagged with its new unit. Rejects unit mismatches.

Inputs: value (required), to_unit (required), from_unit (required). Returns: A scalar physical value with an explicit unit. Attributes: value: The numeric v…

crossmatchA

Match a list of target names to their nearest source in a catalog.

Resolves each name to a position, then finds the nearest catalog source within tolerance_arcsec. Reports both matches (with separation) and any targets with no source inside the tolerance. At most 50 targets per call.

Inputs: targets (required), catalog, tolerance_arcsec. Returns: A normalized cross-match result.

distance_from_parallaxA

Convert a parallax in milliarcseconds to a distance in parsecs.

Rejects non-positive parallaxes, for which distance is undefined, rather than returning a nonsense number.

Inputs: parallax_mas (required). Returns: A scalar physical value with an explicit unit. Attributes: value: The numeric v…

get_ephemerisA

Compute a solar-system body's apparent ephemeris from JPL Horizons.

Returns a time series of ICRS position, distance (delta, in AU), range rate, and V magnitude for a body such as "99942 Apophis", "Ceres", or "C/2023 A3". observer_location is a Horizons code; "500@399" is geocentric. This is the capability the other astronomy MCP servers skip, so prefer it for "where is

Inputs: stop (required), start (required), target (required), step, +1 more. Returns: A body's ephemeris over a range of epochs. Attributes: target: The body queried…

get_small_bodyA

Look up an asteroid or comet's physical and orbital parameters (JPL SBDB).

Returns diameter, absolute magnitude, albedo, rotation period, and osculating orbital elements, each unit-tagged. Pair with get_ephemeris to answer "how big is it and where is it".

Inputs: designation (required). Returns: Normalized small-body physical and orbital summary.

object_dossierA

Resolve an object and, optionally, attach recent papers about it.

Combines object intelligence with a literature lookup in one call. Use when a user asks "tell me about X" and wants both the numbers and the references.

Inputs: name (required), with_papers. Returns: An object plus the papers that measured it.

resolve_objectA

Resolve an astronomical object name or identifier to normalized data.

Returns canonical coordinates (ICRS degrees), object type, cross-identifiers, and measured properties (parallax, proper motion, redshift, magnitudes), each carrying its unit and a provenance record you can cite. Try SIMBAD-style names like "Vega", "M31", "Betelgeuse", or catalog ids. This is usually the first call: downstream tools take the returned RA/Dec.

Inputs: name (required). Returns: A resolved astronomical object with measured properties. Every measured quantit…

search_literatureA

Search the astronomy literature (NASA ADS, or arXiv when no ADS key is set).

Returns normalized paper records with title, authors, year, bibcode, and a resolvable URL. ADS needs a free token configured via skyquery login; without one, SkyQuery falls back to arXiv automatically. rows is capped at 50.

Inputs: query (required), rows, prefer. Returns: result

session_citationsA

Return the deduplicated acknowledgments for every source used this session.

Call this at the end of a research conversation to get a ready-to-paste citations block honoring each service's acknowledgment policy.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: object resolution, ephemeris, small body, literature, conversions, etc. No two tools overlap in functionality, so an agent can easily select the right one for a task.

    Naming Consistency5/5

    All tool names use consistent snake_case and follow a descriptive verb_noun pattern (e.g., resolve_object, get_ephemeris). The naming is predictable and clear, making the tool surface easy to navigate.

    Tool Count5/5

    With 13 tools, the server is well-scoped for an astronomy research assistant. Each tool earns its place, covering essential functions without bloat or triviality.

    Completeness5/5

    The tool surface covers the core astronomy research workflow: object resolution, solar system data, catalog queries, literature search, unit and coordinate conversions, and citation management. No obvious gaps for the stated purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A local MCP server for SkyPortal and Fritz that exposes astronomical transient data (photometry, spectra, classifications, observability) as tools for AI coding assistants.
      23
      BSD 3-Clause
    • A
      license
      B
      quality
      D
      maintenance
      MCP server that provides tools to query 17+ astronomical databases (e.g., SIMBAD, VizieR, Gaia) via HTTP/TAP APIs, enabling AI applications to access astronomical data through natural language.
      23
      20 npm
      2
      BSD 3-Clause
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that equips LLM clients with authoritative astrodynamics tools including TLE/SGP4 propagation, Lambert solving, ground-station access, time-scale and coordinate-frame conversions, and more.
      83 PyPI
      2
      MIT