Astrology API for apps & AI agents

An ephemeris is a precomputed table of planetary positions over time. AstroMCP uses Swiss Ephemeris—the same astronomical library trusted by professional astrologers and planetarium software worldwide. It delivers sub-arcsecond precision for dates from year 1 to 3000 CE, with highest accuracy (ΔT precision) between 1600–2100 CE.

No. AstroMCP is a calculation API that returns raw astronomical data—planetary positions, house cusps, aspects, dignities, and timing. It does not generate horoscope text, personality descriptions, or written interpretations. You create the interpretive layer using your own copywriting, business rules, or by passing the structured data to an LLM.

No astrology knowledge is required. AstroMCP returns structured JSON data containing positions, aspects, and timing information. Developers can pass this data to an LLM to generate human-readable interpretations, or use the values directly in application logic (matching, filtering, scheduling) without understanding astrological concepts.

Both. Most AstroMCP customers are indie developers and small teams building astrology apps, AI agents, dating apps, wellness tools, or content automation. The Pro plan at $59/month covers most use cases. Enterprise customers with custom SLA or volume needs can contact us for tailored terms.

AstroMCP provides endpoints for: natal/birth charts, current transits, transit-to-natal aspects, synastry (relationship compatibility), composite charts, solar returns, lunar returns, planetary returns, secondary progressions, Venus Star Points (VSP) + Venus cycle timing, planetary dignities, aspect calculations, fixed stars, Arabic parts/lots, and chart wheel visualization. See the endpoint catalog below or explore them interactively in Astro Lab.

Yes. The Venus Cycle Suite includes natal Venus Star Points (VSP) plus range-based timing for conjunctions, stations (Rx/D), greatest elongations, and visibility phase metadata. These endpoints are Pro-tier and can be tested interactively in Astro Lab.

AstroMCP supports all major house systems: Placidus, Whole Sign, Equal House, Koch, Regiomontanus, Campanus, Porphyry, Morinus, Alcabitius, Topocentric, and more. Specify the house_system parameter on any chart request. Placidus is the default.

Yes. AstroMCP supports secondary progressions (day-for-a-year), solar returns (annual birthday charts), lunar returns (monthly), and planetary returns (Saturn return, Jupiter return, etc.). These predictive techniques are available via dedicated endpoints with full customization options.

Official SDKs are available for TypeScript/JavaScript (npm) and Python (pip). For other languages, you can generate a client library from our OpenAPI 3.0 specification using tools like openapi-generator. The REST API uses standard JSON over HTTPS, so any HTTP client works.

Yes. Astro Lab is your interactive sandbox—test any endpoint live in the browser without writing code, compare output formats, and generate sample requests. For programmatic testing, your API key works against the production API. There is no separate staging environment; the 7-day or 10k-request trial gives you full access to test your integration.

Authenticate server-to-server requests by passing your API key in the X-API-Key HTTP header. API keys are created and managed in the dashboard. For browser-based dashboard features, authentication uses your logged-in session. Never expose API keys in client-side code.

Standard JSON returns fully-labeled nested objects—verbose but easy to read (~24,000 tokens for a complete natal chart). The llm_v2 format returns the same data as row-based tables with a schema header, reducing token count by approximately 70% (~6,500 tokens). Use llm_v2 when passing chart data to LLMs to reduce costs and fit within context windows.

Calculations are the objective astronomical facts: planet X is at 15°23' Aries in the 7th house, forming a 120° trine to planet Y. Interpretations are the subjective meanings assigned to those facts ('good for relationships'). AstroMCP provides calculations with stable, reproducible schemas. Interpretation is your domain—apply your own rules, voice, or LLM prompts on top of the factual data.

Often, yes. The llm_v2 output format reduces token count by approximately 70% compared to verbose JSON. Smaller payloads mean lower per-request costs with GPT-4, Claude, and other LLMs. Stable schemas also improve prompt caching and make downstream summarization more efficient and consistent.

Use MCP (Model Context Protocol) during development—it allows AI coding agents like Cursor, Windsurf, or Claude to explore endpoints, read schemas, and make test calls interactively. For production applications, call the REST API directly or use the official SDKs for explicit control, better error handling, and predictable behavior. MCP is a developer tool, not a production runtime dependency.

Yes. AstroMCP holds a commercial license for Swiss Ephemeris, which covers all API usage. You do not need to purchase a separate Swiss Ephemeris license to use AstroMCP in commercial products, SaaS applications, or client projects.

The API is designed for production use. Every response includes rate-limit headers (X-RateLimit-*), a unique request ID for debugging, and machine-readable error codes. We monitor uptime continuously. If you need a formal SLA with uptime guarantees, contact us for enterprise terms.

AstroMCP is a stateless calculation API. We do not store birth dates, birth times, birth locations, or chart results. Each request is computed on-demand and the results are returned to you without retention. We log standard operational metadata (timestamps, endpoint, response codes) needed to run, secure, and debug the service.

Most endpoints cost 1 usage unit per request, so 150,000 units equals 150,000 natal charts, transit lookups, or other single-chart calculations. Comparative endpoints that analyze multiple charts cost 1 unit per chart involved: a 2-person synastry request costs 2 units, a 3-person comparison costs 3 units. Batch endpoints follow the same per-chart logic.

Yes. You can cancel your AstroMCP subscription anytime during the 7-day or 10k-request trial period and you will not be charged. No penalties, no tricks. Cancel from the dashboard Account page.

AstroMCP allows 600 requests per minute per API key with up to 10 concurrent in-flight requests. If you exceed these limits, the API returns HTTP 429 (Too Many Requests) with a Retry-After header indicating when to retry. These limits are sufficient for most production applications serving thousands of users.

Yes. Overages are disabled by default—when you hit your included units, requests stop. If you enable overages, you set a monthly spending cap (e.g., $20 maximum overage). If you reach your cap, requests return HTTP 429 until the next billing cycle. This prevents unexpected bills and ensures your application degrades gracefully rather than failing silently.

Timezone and daylight saving time (DST) resolution is built into all calculations. Provide a location or timezone identifier and AstroMCP automatically resolves historical DST rules, avoiding the edge-case bugs that commonly break astrology applications (e.g., births during DST transitions).

Yes. AstroMCP supports both tropical (Western default) and sidereal (Vedic/Eastern) zodiac systems. For sidereal calculations, specify an ayanamsa parameter. Supported ayanamsas include Lahiri (Chitrapaksha), Fagan-Bradley, Raman, Krishnamurti, and others commonly used in Vedic and sidereal Western astrology.