MCP Tools

The AstroLock MCP server exposes tools for querying celestial objects, predicting satellite passes, controlling antenna rotors, checking space weather, and more. It acts as a proxy to the AstroLock FastAPI backend, making the full system accessible from any MCP-compatible client.

Installation

# Register with Claude Code
claude mcp add astrolock-mcp -- uv run --directory packages/mcp astrolock-mcp

The server reads ASTROLOCK_API_URL from the environment (defaults to http://localhost:8000).

---

Object discovery

find_object

Search all catalogs for a celestial object by name. Searches satellites, planets, stars, deep sky objects, comets, and meteor showers.

Parameter	Type	Required	Description
query	string	yes	Search term (e.g., “ISS”, “Mars”, “Vega”, “M31”, “Perseids”)

Returns: Matching objects with their type, ID, magnitude, and description.

Found 3 objects matching 'ISS':
  [SATELLITE] ISS (ZARYA) (id: 25544) -- International Space Station
  [SATELLITE] ISS DEB (id: 43154)
  [SATELLITE] ISS DEB (id: 48274)

semantic_search

Search the AstroLock catalog using natural language. Finds objects based on meaning rather than exact name matching, powered by pgvector embeddings.

Parameter	Type	Required	Default	Description
query	string	yes	—	Natural language search query
limit	int	no	10	Maximum results to return (max 50)

Found 5 results for 'weather satellites in polar orbit':
  [SATELLITE] NOAA 19 (id: 33591) -- Polar-orbiting weather satellite (relevance: 92.3%)
  [SATELLITE] METOP-B (id: 38771) -- EUMETSAT polar weather (relevance: 89.1%)
  ...

whats_up

List all celestial objects currently above the horizon — planets, bright stars, the Moon, Sun, and visible satellites.

Parameter	Type	Required	Default	Description
min_altitude	float	no	10.0	Minimum altitude in degrees above horizon

---

Position & ephemeris

object_position

Get the current sky position of any celestial object.

Parameter	Type	Required	Description
target_type	string	yes	One of: satellite, planet, star, dso, sun, moon, comet, meteor_shower, custom
target_id	string	yes	Object identifier (NORAD ID for satellites, name for planets, database ID for stars/DSOs)

Returns: Altitude, azimuth, distance, RA/Dec coordinates, and above/below horizon status.

ISS (ZARYA) (satellite)
  Status: ABOVE horizon
  Altitude: 42.17 deg
  Azimuth: 215.83 deg
  Distance: 587 km
  RA: 14.221h, Dec: -12.45 deg
  Time: 2026-02-14T03:42:00Z

rise_set_times

Get rise, transit, and set times for a celestial object.

Parameter	Type	Required	Default	Description
target	string	yes	—	Object name (e.g., “mars”, “sun”, “moon”, “jupiter”)
target_type	string	no	”planet”	Object type
days	int	no	1	Number of days to compute (max 7)

---

Pass prediction

predict_passes

Predict satellite passes over the observer’s location. Returns AOS (acquisition of signal), TCA (time of closest approach), and LOS (loss of signal) for each pass.

Parameter	Type	Required	Default	Description
norad_id	int	yes	—	NORAD catalog number (e.g., 25544 for ISS)
hours	int	no	24	Hours ahead to predict (max 168)
min_elevation	float	no	5.0	Minimum peak elevation in degrees

ISS (ZARYA) -- 4 passes from Home QTH:

  AOS: 2026-02-14T05:32:00Z  Az: 210 deg
  TCA: 2026-02-14T05:36:12Z  Alt: 71.2 deg  Az: 135 deg
  LOS: 2026-02-14T05:40:30Z  Az: 42 deg
  Duration: 8m 30s  Max El: 71.2 deg [VISIBLE]

next_pass

Get details of the very next pass of a satellite. A convenience shortcut around predict_passes.

Parameter	Type	Required	Description
norad_id	int	yes	NORAD catalog number (e.g., 25544 for ISS, 27607 for SO-50)

visual_tonight

List objects that will be visible tonight — planets, bright stars, and satellite passes. Useful for planning an evening observation session. Takes no parameters.

---

Rotor control

Hardware required

Rotor tools communicate with physical antenna rotors via the Hamlib rotctld protocol. A configured rotor must be connected and reachable for these tools to function.

rotor_position

Get the current azimuth and elevation of an antenna rotor.

Parameter	Type	Required	Default	Description
rotor	string	no	”default”	Rotor name or ID. “default” selects the first configured rotor.

point_at

Point an antenna rotor at any celestial object. Searches for the target by name, then commands the rotor.

Parameter	Type	Required	Default	Description
target	string	yes	—	Object name (e.g., “Jupiter”, “ISS”, “Vega”, “M31”)
rotor	string	no	”default”	Rotor name or “default”

Pointing Trav'ler at Jupiter:
  Azimuth: 215.3 deg
  Elevation: 42.1 deg

track

Start continuous auto-tracking of a celestial object. The rotor follows the object as it moves across the sky. Use rotor_stop to end tracking.

Parameter	Type	Required	Default	Description
target	string	yes	—	Object name to track
rotor	string	no	”default”	Rotor name or “default”

rotor_stop

Stop the rotor and end any active tracking session.

Parameter	Type	Required	Default	Description
rotor	string	no	”default”	Rotor name or “default”

---

Radio frequencies & Doppler

satellite_frequencies

Get radio frequencies for a satellite — uplinks, downlinks, and beacons.

Parameter	Type	Required	Description
norad_id	int	yes	NORAD catalog number

Frequencies for satellite 25544:
  Downlink     145.800 MHz (FM)
  Uplink       145.200 MHz (FM)
  APRS         145.825 MHz (AFSK)

doppler_correction

Compute live Doppler-corrected frequencies for a satellite. If no specific frequency is given, corrects all known frequencies for that satellite.

Parameter	Type	Required	Default	Description
norad_id	int	yes	—	NORAD catalog number
frequency_mhz	float	no	null	Specific frequency in MHz to correct (omit for all)

Doppler corrections:
  145.800 MHz -> 145.803214 MHz (shift: +3214.2 Hz, range rate: -6.6123 km/s)
  145.825 MHz -> 145.828218 MHz (shift: +3218.0 Hz, range rate: -6.6123 km/s)

---

Sky survey

start_sky_scan

Start an RSSI sky survey. Sweeps the antenna across a grid of azimuth/elevation positions, measuring signal strength at each point to build a heatmap.

Parameter	Type	Required	Default	Description
rotor	string	no	”default”	Rotor name or ID
az_start	float	no	0	Azimuth start angle (0—360)
az_end	float	no	360	Azimuth end angle
el_start	float	no	18	Elevation start angle
el_end	float	no	65	Elevation end angle
step_deg	float	no	2.0	Grid step size in degrees (smaller = more detailed, slower)
rssi_iterations	int	no	10	Signal strength samples per grid point

scan_status

Check progress of a running or completed sky scan.

Parameter	Type	Required	Description
session_id	int	yes	Scan session ID returned by start_sky_scan

scan_results

Get scan results, optionally filtered by minimum signal strength. Returns the strongest signal locations sorted by RSSI.

Parameter	Type	Required	Default	Description
session_id	int	yes	—	Scan session ID
min_rssi	int	no	0	Minimum RSSI value to include (0 for all)

stop_sky_scan

Cancel a running sky scan.

Parameter	Type	Required	Description
session_id	int	yes	Scan session ID to cancel

---

Comets

list_comets

List all comets tracked in the AstroLock database. Returns names, designations, perihelion distances, and orbital eccentricities. Comets are loaded from the IAU Minor Planet Center orbital elements database. Takes no parameters.

comet_position

Get the current sky position of a comet, computed from MPC Keplerian orbital elements.

Parameter	Type	Required	Description
name	string	yes	Comet name or designation (e.g., “Halley”, “C/2023 A3”, “Tsuchinshan-ATLAS”)

refresh_comets

Refresh comet orbital elements from the Minor Planet Center. Downloads the latest CometEls.txt from the IAU MPC. Normally runs automatically every 24 hours. Takes no parameters.

---

Space weather & propagation

space_weather

Get current space weather conditions affecting radio propagation. Returns solar flux index (SFI), K-index, A-index, sunspot number, NOAA storm scales, and HF band condition assessments. Takes no parameters.

band_conditions

Get the current WWV propagation bulletin with HF band assessments. Returns the parsed NOAA/WWV bulletin including solar flux, A/K indices, a day/night condition table for each HF band, and the text forecast. Takes no parameters.

aurora_forecast

Get aurora probability at a specific location using the NOAA OVATION model.

Parameter	Type	Required	Description
lat	float	yes	Latitude in decimal degrees (-90 to 90)
lon	float	yes	Longitude in decimal degrees (-180 to 180)

Returns: Aurora probability percentage, assessment text, and observation/forecast timestamps.

---

Environment

observer_info

Get the current observer location, grid square, and sky conditions. Takes no parameters.

Observer: Home QTH
  Location: 38.8977 N, -77.0365 E
  Altitude: 15 m
  Grid square: FM18lv

set_observer

Update the observer’s location. All position calculations, pass predictions, and sky surveys use this location.

Parameter	Type	Required	Default	Description
latitude	float	yes	—	Latitude in decimal degrees (positive = North)
longitude	float	yes	—	Longitude in decimal degrees (positive = East)
altitude_m	float	no	0.0	Altitude in meters above sea level
name	string	no	null	Optional name for this location

observing_conditions

Get current atmospheric observing conditions at the observer location. Returns an observing score (0—100), cloud cover, visibility, wind speed, temperature, humidity, and precipitation status. Takes no parameters.

Score interpretation:

Score	Rating
80—100	Excellent
60—79	Good
40—59	Fair
20—39	Poor
0—19	Bad

nearby_aircraft

List aircraft currently detected near the observer location via ADS-B. Returns callsigns, altitudes, speeds, headings, vertical rates, origin countries, and squawk codes. Takes no parameters.

RF environment awareness

Knowing what aircraft are nearby helps identify potential interference sources during antenna operations, especially when working with directional antennas on UHF/microwave frequencies.

---

Radiosondes

active_sondes

List currently active radiosondes (weather balloons) being tracked. Returns serial numbers, positions, altitudes, telemetry (temperature, humidity, pressure), frequencies, and flight status (ascending/descending/landed). Takes no parameters.

sonde_predictions

Get landing predictions for currently tracked radiosondes. Returns predicted landing coordinates and times for sondes that are descending or have recently been tracked. Takes no parameters.

---

Tool summary

Quick reference of all 28 tools organized by function:

Category	Tools
Discovery	find_object, semantic_search, whats_up
Position	object_position, rise_set_times
Passes	predict_passes, next_pass, visual_tonight
Rotor	rotor_position, point_at, track, rotor_stop
Radio	satellite_frequencies, doppler_correction
Sky survey	start_sky_scan, scan_status, scan_results, stop_sky_scan
Comets	list_comets, comet_position, refresh_comets
Weather	space_weather, band_conditions, aurora_forecast
Environment	observer_info, set_observer, observing_conditions, nearby_aircraft
Radiosondes	active_sondes, sonde_predictions