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: twelve 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, ChatGPT, or any client that can sign in by OAuth or send an HTTP header.
- Optionally, a free API key from the Basic plan on RapidAPI. Browsing the tool list needs nothing, and tool calls work keyless up to 50 calls a day per network address. With a key, they are metered against the key's quota instead (5,000 a day on Basic, which is a hard limit and is 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"
Leave out --header to start keyless. In Claude on the web or desktop, and in ChatGPT, add a custom connector with the server URL. Those apps call from their own servers, so without a key their users share one keyless allowance. If the app opens the sign-in page, a key entered there meters calls on your plan and keeps them going. Clients that reserve Authorization for their own sign-in (Smithery does) can send X-Api-Key: YOUR_KEY instead; the server accepts both. 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 twelve 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, the server is answering, so any failure later lies in the client configuration.
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 |
| "Is it clear enough to set up the telescope tonight, and when?" | observing_windows, which lays the MET Norway cloud forecast over tonight's moonless dark and answers go or no-go with the window's start and end |
| "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
Without a key, tool calls are served from the keyless API, up to 50 calls a day per network address. With a key, each tool call becomes exactly one metered API request against your key's plan, the same accounting as calling the REST API yourself: Basic is free at 5,000 requests a day, and a conversation that makes five tool calls has used five. Run out of a plan 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 32 routes the endpoint reference documents. It is listed on the official MCP Registry as com.cyclecalcs/astronomy and on Smithery.
Stuck, or found an error in this guide? Contact us at info@cyclecalcs.com.