Using the MCP Server

Craft includes an MCP (Model Context Protocol) server that lets you interact with the entire tracking system through natural language in Claude Code. Instead of constructing API calls by hand, you describe what you want and Claude uses the appropriate tools.

What the MCP server does

The MCP server is a thin proxy layer between Claude and the Craft FastAPI backend. Each MCP tool maps to one or more API endpoints. Claude sees a set of typed functions with descriptions — find_object, predict_passes, point_at, and so on — and calls them based on your conversation.

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

Installation

1. Make sure the Craft API is running (either via Docker or locally).

2. Register the MCP server with Claude Code:

   claude mcp add astrolock-mcp -- uv run --directory /path/to/astrolock/packages/mcp astrolock-mcp

   Replace /path/to/astrolock with the actual path to your Craft checkout.

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

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

Tip

The MCP server is a standard Python package with a uv run entry point. You do not need to install it globally — uv run --directory handles the virtual environment automatically.

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

Here are some things you can ask Claude with the MCP server active:

Finding and tracking a satellite

“Where is the ISS right now?”

Claude calls find_object("ISS") to get the NORAD ID, then object_position("satellite", "25544") to get its current coordinates. You get back altitude, azimuth, distance, and whether it is above the horizon.

Planning a satellite pass

“When is the next good ISS pass?”

Claude calls predict_passes(25544, hours=24, min_elevation=15) and summarizes the results — AOS/TCA/LOS times, duration, and maximum elevation for each pass.

Pointing your antenna

“Point the antenna at Jupiter”

Claude calls point_at("Jupiter"). The tool searches for Jupiter, resolves the default rotor, checks that Jupiter is above the horizon and above the minimum elevation, then sends the position command. You get back the azimuth and elevation it pointed to.

Checking propagation conditions

“Are conditions good for satellite work right now?”

Claude calls space_weather() to get the current solar flux, K-index, and NOAA storm scales, then interprets the results in context. High K-index or active geomagnetic storms can affect VHF/UHF propagation and satellite signal quality.

Doppler correction for a contact

“What frequency should I tune to for the ISS repeater on 437.800 MHz?”

Claude calls doppler_correction(25544, 437.800) and returns the corrected frequency accounting for the satellite’s current range rate.

Full observation session

“What is visible tonight and which passes are worth tracking?”

Claude calls visual_tonight() to get the evening sky, then predict_passes for any interesting satellites in the list. It can then help you plan which passes to track, set up the rotor, and compute Doppler corrections for each one.

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.