Give your AI assistant the real sky
A language model asked "when is the next eclipse visible from Denver?" will guess fluently. Connected to the CycleCalcs MCP server, it stops guessing: eleven read-only tools put computed ephemerides one call away, and the assistant's answer carries the instants, magnitudes and visibility verdicts the engine actually computed.
What you need
- An MCP-capable client: Claude Code, Claude on the desktop or web, or any client that can send an HTTP header.
- A free API key from the Basic plan on RapidAPI. Browsing the tool list needs nothing; tool calls are metered against the key's quota (5,000 a day on Basic, hard limit, never billed).
Step 1: connect a client
The server lives at https://www.cyclecalcs.com/mcp (streamable HTTP, stateless, JSON responses). In Claude Code it is one command:
claude mcp add --transport http cyclecalcs https://www.cyclecalcs.com/mcp --header "Authorization: Bearer YOUR_KEY"
In Claude on the web or desktop, add a custom connector with the server URL and set the Authorization header where your plan offers custom headers. Clients that reserve Authorization for their own sign-in (Smithery does) can send X-Api-Key: YOUR_KEY instead; the server accepts both. ChatGPT's own connectors cannot attach it yet (they authenticate with OAuth or not at all), but developers on the OpenAI Responses API can pass the key in the mcp tool's authorization field. The full client matrix is on the MCP server page.
Step 2: prove the wire before trusting a client
The tool list is public, so you can watch the server answer with nothing but curl:
curl -X POST "https://www.cyclecalcs.com/mcp" -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
The response lists all eleven tools with their input and output schemas, starting with astro_sky_today, whose description begins: "One-call snapshot of the whole sky for a place and moment". If that works, any failure later is client configuration, not the server.
Step 3: ask real questions
The tools are deliberately question-shaped, so plain language routes well:
| You ask | The assistant calls |
|---|---|
| "What is in the sky tonight from Lisbon?" | astro_sky_today with place: "Lisbon", resolved server-side; astro_find_place exists to disambiguate a name or reverse-geocode |
| "Which night in the next two weeks has the longest moonless dark window here?" | astro_dark_window, which ranks up to 62 nights |
| "When is the next eclipse I can actually see from Denver?" | astro_eclipses, whose answer includes local circumstances and an explicit visible-from-here |
| "When does Venus next reach greatest elongation?" | astro_planet_events, the Mercury and Venus apparition calendar |
The other tools cover sunrise and twilight (astro_sun), the Moon's state and calendar (astro_moon, astro_moon_phases), precise positions and rise/set for any body (astro_positions, astro_rise_set), and all eight planets at a glance (astro_planet_board). Every tool is read-only and annotated as such, and conventions ride in the data itself: numeric field names carry their units (_deg, _km, _fraction) and coordinate paths state their frame and epoch (equatorial.j2000), so the assistant can state conventions instead of hand-waving them.
How it is metered, honestly
Each tool call becomes exactly one metered API request against your key's plan, the same accounting as calling the REST API yourself. The asymmetry with the keyless REST API is deliberate: tool calls route through the metering gateway so each caller spends their own quota, and without a key every assistant everywhere would share one anonymous bucket. Basic is free at 5,000 requests a day; a conversation that makes five tool calls has used five. Run out and the tool returns a structured quota error with a retry time rather than a silent failure. The paid plans (Pro, Ultra, Mega) raise rate and range ceilings; they never change any answer.
The server adds no endpoints and changes no contracts: it is a protocol adapter in front of the same 29 routes the endpoint reference documents. It is listed on the official MCP Registry as com.cyclecalcs/astronomy and on Smithery.