polemaster-mcp

A Model Context Protocol (MCP) server that helps southern-hemisphere astrophotographers complete QHY PoleMaster polar alignment under light-polluted skies.

Sigma Octantis and its surrounding pattern stars (~magnitude 5.4–6.6) are notoriously hard to spot visually when Bortle skies wash them out. This server plate-solves a saved PoleMaster BMP frame using ASTAP, then overlays labelled circles on Sigma Octantis and the PoleMaster pattern stars so you can match the PoleMaster overlay with confidence.

Originally developed for use with Claude Desktop, but should work with any MCP-compatible client.

What it does

Four tools exposed over MCP:

Tool	Purpose
pm_check_setup	Verifies ASTAP install, star databases (W08/G05/G17), and frames directory.
pm_solve_frame	Plate-solves a saved PoleMaster BMP via ASTAP CLI. Writes a .wcs sidecar.
pm_annotate_frame	Draws Sigma Octantis and pattern stars on the frame. Outputs *_annotated.png.
pm_get_pattern_stars	Returns J2000 coordinates for SCP region stars (filterable by role/magnitude).

Prerequisites

• Windows (tested on Windows 10/11; may work on other OSes but ASTAP paths and fonts are Windows-defaulted).
• Python 3.10+
• ASTAP installed, with a wide-field star database suitable for ~11° fields of view. Recommended: W08 or G05. (G17 alone is too narrow-field for PoleMaster frames.)
• QHY PoleMaster hardware and the PoleMaster Qt software — used to capture frames via File → Save as BMP.
• An MCP-capable client (e.g. Claude Desktop).

Installation

cd C:\Projects       # or wherever you want the repo to live
git clone https://github.com/LaughingBeagles/polemaster-mcp.git
cd polemaster-mcp
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt

On Linux/macOS, substitute the venv activation step with source .venv/bin/activate.

Configuration

The server reads two environment variables (with fallbacks):

Variable	Default	Purpose
ASTAP_PATH	C:\Program Files\astap\astap.exe	Full path to the ASTAP executable.
POLEMASTER_FRAMES	D:\PoleMaster_Frames (example)	Directory where you save PoleMaster BMPs. Set this to any folder you like. Created on first use if missing.

Set them via your MCP client's env block (see claude_desktop_config.example.json) or via your shell before running the server.

Claude Desktop setup

Copy claude_desktop_config.example.json entries into your Claude Desktop config file, adjusting the paths:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Restart Claude Desktop. The server should appear as polemaster_mcp in the connected MCPs list.

Usage

1. Rough-align the mount due south with a compass.
2. Start the PoleMaster Qt software, select the South region, and capture a frame covering the pole.
3. File → Save as BMP into your POLEMASTER_FRAMES directory.
4. In Claude Desktop (or any MCP client), ask something like:

   "Solve and annotate D:\PoleMaster_Frames\20260424_pole.bmp" (Substitute your own path and filename.)

5. Claude calls pm_solve_frame then pm_annotate_frame. Open the resulting *_annotated.png on a second monitor or tablet and use it to identify the pattern in the PoleMaster live view.

How it works

pm_solve_frame invokes ASTAP via CLI with hints tuned for the South Celestial Pole (RA ≈ 21.14h, Dec ≈ −89°, FOV ≈ 11°). ASTAP writes a FITS-style .wcs sidecar, which pm_annotate_frame parses to project the star catalog (star_catalog.py) onto pixel coordinates using a standard gnomonic (tangent-plane) projection.

The southern-hemisphere star catalogue is embedded (Sigma Oct plus pattern and reference stars near the SCP). Catalogue values are J2000 decimal degrees.

Northern hemisphere?

Not supported out of the box — the star catalogue is southern-only. Contributions welcome: extend star_catalog.py with Polaris and the northern pattern stars, and change the default ra_hint/dec_hint in pm_solve_frame.

Troubleshooting

• pm_check_setup says ASTAP not found: set ASTAP_PATH to the actual path.
• Plate-solve fails: increase search_radius, verify W08/G05 is installed, check PoleMaster focus.
• Annotator runs but nothing visible on frame: check the solve's centre_ra_deg/centre_dec_deg — if they're far from the pole, the PoleMaster was pointed the wrong way.
• FastMCP import fails: ensure fastmcp<3.0.0 is installed (3.x has breaking changes).

Licence

MIT — see LICENSE.

Acknowledgements

• ASTAP — Han Kleijn's excellent plate solver.
• QHYCCD for the PoleMaster hardware.
• FastMCP for the MCP server framework.
• Developed interactively with Anthropic's Claude (Opus 4.6 + Sonnet 4.6) across several sessions.