CycleCalcs Astronomy

npx add-mcp 'https://www.cyclecalcs.com/mcp'

The API as an MCP server

The CycleCalcs astronomy API speaks the Model Context Protocol, so Claude and other MCP clients can call it as tools instead of raw HTTP. It is the same API underneath: eleven read-only tools, each backed by one live /v2 endpoint, computed by the same engine and, with a key, metered on the same plans.

https://www.cyclecalcs.com/mcp

The endpoint is a stateless Streamable HTTP server (POST only, JSON responses). It speaks MCP specification revision 2026-07-28 and the earlier 2025 handshake revisions, so current and older clients both connect.

Authentication and metering

No key is needed to start. Tool calls without a key are served from the keyless API, up to 50 calls a day per network address, counted over a rolling 24 hours. Callers who share an address, such as an office network or an AI app whose servers make the calls for all its users, share one allowance until they connect with a key. A sign-in without a key is counted on its own and against its address, so it never adds to what the address has left. The count is kept by each running server instance, so it is approximate.

Past the allowance, a keyless call is answered with HTTP 401 and a sign-in challenge, which MCP clients that follow the authorization spec answer by opening a sign-in. A client that cannot sign in sends a key in a header instead, as below. A client already signed in without a key gets a tool result saying how to continue with one.

To have tool calls metered on your own plan, send a CycleCalcs API key on every request in the Authorization header:

Authorization: Bearer YOUR_RAPIDAPI_KEY

Keys come from the RapidAPI listing; the Basic plan is free. A call made with a key is forwarded through the RapidAPI gateway with that key, so it counts against your plan exactly as a direct REST call would, and your plan's limits apply unchanged. The key never goes in the URL.

The key may also be sent as a raw value in an X-Api-Key header, with no Bearer prefix:

X-Api-Key: YOUR_RAPIDAPI_KEY

Both headers are equally supported. The alternative exists because some directories and gateways reserve Authorization for their own sign-in and can only forward a differently named header.

Browsing the server needs no key. initialize and tools/list are answered without one, so a client, an inspector or a directory can connect and read all eleven tool schemas before anyone has signed up for anything.

Connecting a client

Claude and ChatGPT. Add the server URL above as a custom connector. Both apps call the server from their own servers, so without a key a connector shares the keyless allowance of those addresses with the app's other users, and a key is what keeps its calls going. If the app opens the sign-in page, enter the key there: calls are then metered on your plan, and checking the key uses one request of it. To stop a key being used here, regenerate it in your RapidAPI dashboard.

Claude Code, with a key:

claude mcp add --transport http cyclecalcs https://www.cyclecalcs.com/mcp --header "Authorization: Bearer YOUR_KEY"

Leave out --header to start keyless. Any MCP-capable client that can send a request header works the same way; the server needs no session support from the client.

For OAuth client authors. Discovery starts at /.well-known/oauth-protected-resource/mcp. The server supports OAuth 2.1 with PKCE S256, dynamic client registration and client ID metadata documents, for public clients only. Past the allowance, a client signed in without a key, and a call carrying the OpenAI Apps SDK's openai/ request metadata, get the challenge inside the tool result instead of a 401: _meta["mcp/www_authenticate"], with error="insufficient_scope", which is the form that SDK documents for opening account linking.

For a start-to-finish walkthrough, with the wire proven by curl before any client is configured and example prompts mapped to the tools they invoke, follow the build guide: give your AI assistant the real sky.

The eleven tools

Tool	What it answers	Backed by
astro_sky_today	The whole sky for a place and moment: moon, planets up, next eclipse, sun times	/v2/today
astro_sun	Sunrise, sunset, solar noon, day length and the three twilights, single day or series	/v2/sun
astro_moon	Moon phase, illumination, distance, libration and next quarters	/v2/moon
astro_moon_phases	The phase calendar: every new, quarter and full moon with supermoon status and names	/v2/phases
astro_positions	Exact positions for up to 20 bodies in stated frames, instant or time grid	/v2/positions
astro_rise_set	Rise, transit and set for one body, with explicit polar status	/v2/rise-set
astro_eclipses	Solar and lunar eclipses with local circumstances and a visible-from-here answer	/v2/eclipses
astro_dark_window	The genuinely dark, moonless observing window per night, ranked across nights	/v2/dark-window
astro_planet_board	All eight planets at a glance: brightness, retrograde state, worth looking tonight	/v2/planet-board
astro_planet_events	Planet events: Mercury and Venus apparitions, Mars to Neptune conjunctions with the Sun, quadratures and oppositions, and constellation entries	/v2/planet-events
astro_find_place	Place name to coordinates and timezone, or reverse lookup	/v2/places

Tool results carry the API's own field names, which state their units (_deg, _km, _fraction) and reference frames (equatorial.j2000), plus any warnings the API attached. Errors pass through the API's RFC 9457 problem documents unchanged, including the supported date range of 1700 to 2200.

Which REST routes the tools reach

MCP tool calls work without a key up to 50 calls a day per network address, and with a RapidAPI key past that. The REST API needs none: each route below answers a plain HTTPS request at the free Basic tier. An assistant limited to MCP can reach only the routes that have a tool.

Of the data routes below, 11 are reached by a tool and the other 15 are REST only. The table leaves out /v2, /v2/conventions, /v2/enums and /v2/attribution, which describe the API itself rather than the sky.

REST route	MCP tool
/v2/positions	astro_positions
/v2/rise-set	astro_rise_set
/v2/sun	astro_sun
/v2/moon	astro_moon
/v2/time	REST only
/v2/seasons	REST only
/v2/apsides	REST only
/v2/moon-nodes	REST only
/v2/eclipses	astro_eclipses
/v2/planet-board	astro_planet_board
/v2/retrogrades	REST only
/v2/conjunctions	REST only
/v2/separation	REST only
/v2/rarity	REST only
/v2/cycles	REST only
/v2/twilight	REST only
/v2/dark-window	astro_dark_window
/v2/sidereal-time	REST only
/v2/equation-of-time	REST only
/v2/libration	REST only
/v2/jupiter-moons	REST only
/v2/sky-quality	REST only
/v2/places	astro_find_place
/v2/phases	astro_moon_phases
/v2/planet-events	astro_planet_events
/v2/today	astro_sky_today

Rights

Tool results are computed astronomical facts and carry the same rights as the REST API: use them without restriction or attribution. The one exception is unchanged too: place lookups return GeoNames data under CC BY 4.0, and those results include the required credit, which must be preserved when shown.

Building against the REST API instead? Start at the API overview or the endpoint reference. The MCP server adds no endpoints and changes no contracts; it is a protocol adapter in front of the same API, and the coverage table shows which routes it reaches.

All API documentation

• Developer hub: What to build and where every tool lives: API, MCP server, widgets.
• Overview and playground: What the API answers, the plans, and a live try-it panel.
• Endpoint reference: Every route, its parameters and a real captured response.
• Keys and plans: How to get a key, what each plan raises, and how quotas are counted.
• Error codes: The registered problem documents, one entry per code.
• Accuracy and residuals: Measured error against reference ephemerides, and the conventions every response states.
• Versioning policy: What is frozen, what may change, and how a change is announced.
• Status and limits: Rate windows, range caps and the current service position.
• MCP server: The same engine as tools an AI assistant can call directly.
• Version 1 (frozen): The original seven endpoints, still served and never changing shape.
• Terms of use: What you may do with the answers, including in commercial products.