Using the MCP Server

Craft includes an MCP server — another interface to the entire tracking system, alongside the REST API and WebSocket streams. Any MCP client can connect to it. Instead of constructing API calls by hand, a client discovers the available tools and calls them directly.

What the MCP server does

The MCP server is a thin proxy layer in front of the Craft FastAPI backend. Each MCP tool maps to one or more API endpoints. Clients discover typed functions with descriptions — find_object, predict_passes, point_at, and so on — and call them as needed.

The MCP server itself does no computation. It formats requests to the API, parses responses, and returns structured text.

Installation

Make sure the Craft API is running (either via Docker or locally).
Register the MCP server with your client. The server is a standard Python package that runs via uv:
Terminal window
```
uv run --directory /path/to/astrolock/packages/mcp astrolock-mcp
```
Replace /path/to/astrolock with the actual path to your Craft checkout.

If the Craft API is not running on localhost:8000, set the base URL:

export ASTROLOCK_API_URL=https://your-domain
uv run --directory /path/to/astrolock/packages/mcp astrolock-mcp

The server uses the stdio transport — it communicates over stdin/stdout using JSON-RPC. How you register it depends on your client. Most clients accept a JSON config like:

{
  "mcpServers": {
    "astrolock-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/astrolock/packages/mcp", "astrolock-mcp"],
      "env": {
        "ASTROLOCK_API_URL": "http://localhost:8000"
      }
    }
  }
}

Available tools

Object search and position

Tool	Description
`find_object`	Search all catalogs by name. Works with satellite names, planet names, star names, Messier/NGC designations, comet names.
`object_position`	Get current sky coordinates (altitude, azimuth, RA/Dec, distance) for any object by type and ID.
`semantic_search`	Natural language search across the catalog using vector embeddings.
`whats_up`	List everything currently above the horizon at your observer location.

Pass prediction

Tool	Description
`predict_passes`	Predict satellite passes for the next N hours with minimum elevation filter.
`next_pass`	Get the next pass of a specific satellite.
`visual_tonight`	List objects visible tonight — planets, stars, and satellite passes.
`rise_set_times`	Get rise, transit, and set times for a planet, the Sun, or the Moon.

Rotor control

Tool	Description
`point_at`	Point a rotor at any named object. Searches for the target, resolves the rotor, and sends the command.
`track`	Start continuous auto-tracking of a target. The rotor follows the object across the sky.
`rotor_stop`	Stop the rotor and end any active tracking session.
`rotor_position`	Read the rotor’s current azimuth and elevation.

Radio and propagation

Tool	Description
`satellite_frequencies`	Get known radio frequencies (uplinks, downlinks, beacons) for a satellite.
`doppler_correction`	Compute live Doppler-corrected frequencies for a satellite based on its range rate.
`space_weather`	Current solar indices (SFI, K-index, A-index), NOAA storm scales, and HF band conditions.
`band_conditions`	The NOAA/WWV propagation bulletin with day/night band assessments.
`aurora_forecast`	OVATION aurora probability at a given latitude/longitude.

Sky survey

Tool	Description
`start_sky_scan`	Start an RSSI sky survey, sweeping the antenna across a grid of positions.
`scan_status`	Check progress of a running scan.
`scan_results`	Get scan data, optionally filtered by minimum signal strength.
`stop_sky_scan`	Cancel a running scan.

Observer

Tool	Description
`observer_info`	Get the current observer location, grid square, and altitude.
`set_observer`	Update the observer’s latitude, longitude, and altitude.

Example conversations

Most MCP clients accept natural language — you ask a question and the client figures out which tools to call. Here are some real interactions showing prompts, tool calls, and responses.

Where is the ISS?

“Where is the ISS right now?”

The client calls find_object("ISS") to resolve the name, then object_position("satellite", "25544"):

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-18T03:42:00Z

“What frequencies does it have?”

Frequencies for satellite 25544:

  RX Downlink  145.800 MHz (FM)
  TX Uplink    145.200 MHz (FM)
  APRS         145.825 MHz (AFSK)

“What’s the Doppler shift on the downlink right now?”

Doppler correction for 145.800 MHz:
  Corrected: 145.803214 MHz
  Shift: +3214.2 Hz
  Range rate: -6.612 km/s
  Time: 2026-02-18T03:42:15Z

Planning a pass

“When is the next good ISS pass — at least 30 degrees?”

The client calls predict_passes(25544, hours=24, min_elevation=30):

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

  AOS: 2026-02-18T19:23:15Z  Az: 245 deg
  TCA: 2026-02-18T19:28:42Z  Alt: 67.3 deg  Az: 180 deg
  LOS: 2026-02-18T19:34:09Z  Az: 135 deg
  Duration: 10m 54s  Max El: 67.3 deg [VISIBLE]

  AOS: 2026-02-19T06:41:03Z  Az: 310 deg
  TCA: 2026-02-19T06:45:18Z  Alt: 41.2 deg  Az: 025 deg
  LOS: 2026-02-19T06:49:50Z  Az: 098 deg
  Duration: 8m 47s  Max El: 41.2 deg

The first pass peaks at 67 degrees, lasts nearly 11 minutes, and is sunlit — that’s a strong candidate for both visual and radio work.

Pointing the antenna

“Point the antenna at Jupiter”

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

“Now track the ISS for the next pass”

The client calls track("ISS"). The rotor begins following the satellite across the sky, updating position continuously until the pass ends or you stop it.

“Stop tracking”

Rotor stopped. Tracking session ended.

What’s up tonight?

“What can I see tonight?”

Tonight's sky -- 8 objects:

  Venus              [planet   ] Alt: 42.3 deg  mag -3.9
  Jupiter            [planet   ] Alt: 28.1 deg  mag -2.5
  ISS                [satellite] Alt: 65.0 deg
  Vega               [star     ] Alt: 72.4 deg  mag  0.0
  M31                [dso      ] Alt: 48.2 deg

“How about weather satellites in a polar orbit — anything coming over?”

The client calls semantic_search("weather satellites polar orbit"):

Found 5 results for 'weather satellites polar orbit':

  [SATELLITE] NOAA 19 (id: 33591) (mag 3.2) -- Polar-orbiting weather (relevance: 92.3%)
  [SATELLITE] METOP-B (id: 38771) -- EUMETSAT polar weather (relevance: 89.1%)
  [SATELLITE] NOAA 18 (id: 28654) (mag 3.5) -- Polar-orbiting weather (relevance: 87.4%)

“When’s the next NOAA 19 pass?”

NOAA 19 -- 1 pass from Home QTH:

  AOS: 2026-02-18T21:14:30Z  Az: 195 deg
  TCA: 2026-02-18T21:21:45Z  Alt: 38.7 deg  Az: 110 deg
  LOS: 2026-02-18T21:28:58Z  Az: 035 deg
  Duration: 14m 28s  Max El: 38.7 deg

Checking propagation

“Are conditions good for satellite work right now?”

Space Weather Summary
========================================
  Solar Flux Index (SFI): 145
  Sunspot Number:         78
  K-index:                2 (quiet)
  A-index:                7

NOAA Scales:
  Radio Blackout:     R0 (None)
  Solar Radiation:    S0 (None)
  Geomagnetic Storm:  G0 (None)

Last updated: 2026-02-18T18:00:00Z

K-index of 2 is quiet — good conditions for VHF/UHF satellite work. Higher K values (4+) can cause signal fading and polarization issues on passes near the auroral oval.

Connecting to a remote Craft instance

If your Craft instance runs on a remote server, set the ASTROLOCK_API_URL environment variable before starting the MCP server:

export ASTROLOCK_API_URL=https://space.your-domain.com

The MCP server prepends this base URL to all API calls. All tool functionality works identically whether the API is local or remote.