Sky Compass MCP

An MCP server that tells you where a celestial object is in the sky for your location. Give it a name such as Moon, Mars, or Andromeda Galaxy and it returns:

• the magnetic compass bearing in degrees and as a 16-point direction (N, NNE, … ENE … W, NW, …)

• the altitude (vertical angle above the horizon) to look up to

• whether the object is above the horizon right now

It also converts raw sky coordinates (right ascension and declination) into the same output.

It is built on the official MCP Python SDK (FastMCP, pinned to mcp>=1.2,<2).

Install

pip install sky-compass-mcp

Or run it without installing, using uv:

uvx sky-compass-mcp

Related MCP server: Celestial Position MCP Server

Use with an MCP client

Add the server to your client's MCP configuration, for example:

{
  "mcpServers": {
    "sky-compass": {
      "command": "uvx",
      "args": ["sky-compass-mcp"]
    }
  }
}

If uvx is not available, use "command": "sky-compass-mcp" after installing with pip.

Tools

Streaming

track_object takes start_time_utc, duration_s (up to 3600), and interval_s (0.1 to 60). When the client sends a progressToken in _meta, each sample is delivered as a standard notifications/progress message, paced in real time. The final result holds the sample count and the first and last samples. Without a token, the result contains all samples.

Each sample carries magnetic_bearing_deg, altitude_deg, altitude_rate_deg_s, and magnetic_bearing_rate_deg_s, which a telescope controller can compare against its gyroscope, accelerometer, and magnetometer readings.

Example

Request:

{
  "object_name": "Mars",
  "latitude": 28.6139,
  "longitude": 77.2090,
  "elevation_m": 216,
  "time_utc": "2026-11-02T20:00:00Z",
  "magnetic_declination_deg": 0.5
}

Response (abridged):

{
  "object": "Mars",
  "altitude_deg": 13.654,
  "above_horizon": true,
  "magnetic_bearing_deg": 77.9,
  "compass_direction": "ENE",
  "compass_direction_name": "East-northeast"
}

Supported objects

• Solar system: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune

• Fixed objects: Andromeda Galaxy (M31), Triangulum Galaxy (M33), Whirlpool Galaxy (M51), Orion Nebula (M42), Pleiades (M45), Large Magellanic Cloud, Galactic Center (Sagittarius A*), Polaris, Sirius, Vega, Betelgeuse

• Anything else: names are looked up in SIMBAD when remote lookup is enabled. Results are cached in the local SQLite catalog.

Pluto is not included.

Configuration

SIMBAD lookups need internet access. The seeded catalogue works offline.

Scope: read-only

This server only computes angles. It does not control motors or read sensors. Sensor fusion and motor control belong in a separate client that applies its own limits and safety checks.

Magnetic declination

A magnetic compass points to magnetic north, which differs from true north by the local magnetic declination. This server computes bearings from true north, then subtracts the declination you pass in magnetic_declination_deg (east positive). It does not bundle a magnetic model, so the default is 0, which means magnetic equals true. Look up your location's declination for the current date, for example with NOAA's calculator, before using the bearing with a real compass.

Accuracy

Altitude is geometric. Atmospheric refraction raises low objects by up to about 0.5°. This is suitable for finding objects by eye and is not for navigation or professional observation.

Run from source

python -m sky_compass_mcp          # starts the stdio server
python -m unittest discover -s tests -v
SKY_COMPASS_LIVE=1 python -m unittest tests.test_simbad_live -v   # live SIMBAD (needs internet)

Protocol

Built on the official MCP Python SDK (FastMCP). Served over stdio by default, or over Streamable HTTP at POST /mcp with --transport http. Logs go to stderr only.

The fixed-object coordinates are approximate and should be checked against SIMBAD before publishing. The SIMBAD client tries each configured mirror in turn. Live tests (SKY_COMPASS_LIVE=1) pass through the Harvard mirror when the CDS host is unreachable, but each unreachable mirror adds its full timeout to a lookup.

Publishing

1. Build: python -m build

2. Check: twine check dist/*

3. Upload to PyPI: twine upload dist/*

4. Register in the MCP Registry with mcp-publisher publish using server.json. Update the repository URL and the name namespace to match your GitHub account first.

License

MIT