Zodiacs
Birth charts, compatibility, horoscopes and the sky, from planet positions tested against NASA JPL.
Hosted MCP Server
npx add-mcp 'https://zodiacs.org/mcp'Installs into Claude Code, Codex, Cursor and more
Documentation
Build with the sky
Zodiacs connects AI assistants to the Zodiacs engine in two ways: a hosted MCP server at https://zodiacs.org/mcp for any assistant that accepts remote MCP connections, and a local developer plugin that runs on your own machine. Public directory listings remain release gates.
Looking for the app? See the cards, short demo and current connection options for ChatGPT and Claude.
Connect it
To use it in Claude, open Customize, then Connectors, add a custom connector and enter https://zodiacs.org/mcp. Other assistants that accept remote MCP connections use the same address. Then ask one of the questions below.
The hosted server
The hosted server lists 19 tools. It calculates the sky at a moment you name, reads birth charts, compares two charts, and serves the dated Sun-sign horoscopes the site publishes. Answers give times on the person's own clock where a time zone is known. Calculated facts are kept apart from what astrology reads into them, and each reading carries a reading-confidence label that says how specific the details were, never the odds that something happens. Answers include UTC, a display timezone, calculation receipts and numerical limits. Event-search completeness is tested, not proven.
The horoscopes come from the site's daily edition. It keeps the editions for the day before, the day of and the day after, so a reader in any time zone gets the reading written for their own date. Horoscopes are interpretation, for reflection.
Tools that need no birth details
get_capabilitiesLists what Zodiacs can do, its limits and how it handles privacy.get_skyShows where the Sun, Moon and planets are now, or at a moment you name, with the Moon’s phase.get_upcoming_eventsLists planets changing sign, turning retrograde or direct, and new and full Moons, for up to 92 days.check_sky_factChecks a claim such as “Is Mercury retrograde today?” and answers yes, no, or that it depends on the time zone.get_horoscopeShows a Sun-sign horoscope for today (general, love or career) or for this week.get_famous_chartLooks up the birth chart of a famous person Zodiacs publishes, and says so when it has none.get_sky_calendarGives the link to follow the Zodiacs sky calendar in Google Calendar, Apple Calendar or Outlook.get_horoscope_periodShows a Sun-sign horoscope for a month, a year, or a love or career week.get_chinese_zodiacGives the Chinese zodiac animal, element and yin or yang for a birth date or a year.explain_astrologyExplains a basic astrology topic in plain words, with links to the Zodiacs pages it comes from.open_chart_studioOpens Chart Studio, a birth chart you fill in yourself inside a panel; the assistant sees only what you choose to share.
Tools that take a birth date, a place or another date you give
get_occasion_skyDescribes the sky on a day that matters, such as a wedding, an anniversary or a move, and rates the date from 0 to 100.get_life_milestonesLists the Jupiter returns, Saturn returns and Uranus opposition that follow from a birth date, with dates and ages.get_compatibilityCompares two people’s birth charts: their signs, the closest contacts between their planets and their elements.find_chart_twinsFinds famous people who share your Sun sign, Moon sign or both.get_birthdayDescribes the sky on a birthday: the Sun’s sign, its decan and whether the date falls on a cusp.get_natal_chartReads one birth chart in the conversation: Sun, Moon and rising signs, planets, houses, aspects and balance.get_personal_transitsLists dated transits to your own birth chart, with what astrology traditionally reads into each.find_birthplaceFinds a town or city by name and returns its coordinates and time zone for the chart tools.
get_horoscope and get_chinese_zodiac also accept a birth date when you want a personal answer; neither needs one. The sky calendar, the horoscope and Chart Studio can open as a panel from the assistant's sidebar as well as in the conversation. Chart Studio asks for birth details inside its panel and calculates there; the assistant receives only a selection the person reviews and shares.
Things to ask
- “What changes in the sky this week in Mexico City?”
- “Is Mercury retrograde right now?”
- “Show today's horoscope for Leo.”
- “I was born on 14 February 1988 at 06:15 in Lisbon. What does my birth chart say?”
- “What was the sky like on our wedding day, 12 September 2020?”
- “Add new and full Moons to my Google Calendar.”
An answer should be useful in the conversation. Links to the Moon tool, lunar calendar and methodology offer optional further exploration.
What it will not do
- It gives no betting tips, sports picks, investment timing, election forecasts or health predictions, and it guarantees no outcome. It gives no financial or medical advice.
- It refuses a birth date less than 13 years ago, and one still to come. Zodiacs is not directed at children under 13, so do not send a child's name, birth date or birthplace.
- It gives no romance or attraction framing for anyone under 18.
- Birth details are never stored or logged. A date you give is used for that answer only. No tool listed here saves a chart.
- Birth details are never put in links. A link never carries a birth year, a birth time, a birthplace or the names you give; a birthday link carries only the month and day.
- It schedules nothing and sets no reminders.
get_sky_calendarhands over a calendar link that you add to your own calendar app yourself. get_upcoming_eventsdoes not list eclipses or every aspect. Eclipses appear in the sky calendar feed and in the monthly and yearly horoscopes.- It never guesses a birth time or a sign, and it tells the assistant to ask before using someone else's birth details.
The server keeps a daily count of how often each tool is used, split only by deployment and by the kind of assistant that called it: ChatGPT, Claude or another. The assistant you use can receive what you send and what comes back, under its own privacy policy. The privacy policy has the detail.
Troubleshooting
- A tool refuses a recent birth date. Any birth date less than 13 years ago, or in the future, gets a fixed refusal and no chart, card or reading. For someone 13 or older, give their own birth date.
- You do not know the birth time. Leave it out; never guess it. The chart then has no rising sign and no houses, and where the Moon or a planet changed sign that day it lists both signs.
- “A birth time or a place needs its time zone.” Give the birthplace's time zone with the time.
find_birthplacereturns it for a town or city. - Times look wrong for where you are. Tell the assistant your city or time zone. Without one, the tools that depend on today's date use UTC and say so, and a date-only sky check can answer that it depends on the time zone.
- A birth time fell on a clock change. When the local clock skipped that time or showed it twice, the chart says which moment it used. Check the time with the person if it matters.
- A place is not found. The index lists towns and cities of 15,000 people or more. Try another spelling, add the country, or give the nearest larger town. A street address is refused.
- A famous person is not found. Zodiacs answers only for the people it publishes charts for, and says so when it has none.
- “Zodiacs is busy. Try again in a minute.” The server has a shared request limit. Wait a minute and ask again.
Support
For help with the connector, email admin@zodiacs.org. Say which assistant you use, what you asked and what came back. Leave out real names and birth details; a made-up date that shows the same problem is enough. Developer support lists the other routes.
Build and verify an integration
Zodiacs Developer provides skills for building with the engine, checking output and testing an integration. Its local stdio server adds natal-chart calculation and record comparison to the public-sky tools. It opens no listener or outbound connection. The existing local MCP adapter remains available separately.
In a checkout, run npm ci and npm test in plugins/zodiacs-developer. The plugin contains pinned dependencies, three skills and runnable synthetic sky/calendar examples. Installation details and review evidence are in the plugin directory.
What local means
The developer server computes on its machine. The assistant provider can still receive the arguments and results. Hosted sky calculations run on Zodiacs infrastructure. Public-sky tools need no birth details; derived natal positions remain personal data. Read the AI integration privacy explanation before connecting personal records.
Use the published calculation engine in external projects and preserve its notices. Site-derived candidate code retains the site's license. A receipt supports reproduction; it does not certify an imported record's authenticity or validate astrological interpretation.
For current support and known calculation limitations, see developer support and independent-reference conformance.