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_capabilities Lists what Zodiacs can do, its limits and how it handles privacy.
  • get_sky Shows where the Sun, Moon and planets are now, or at a moment you name, with the Moon’s phase.
  • get_upcoming_events Lists planets changing sign, turning retrograde or direct, and new and full Moons, for up to 92 days.
  • check_sky_fact Checks a claim such as “Is Mercury retrograde today?” and answers yes, no, or that it depends on the time zone.
  • get_horoscope Shows a Sun-sign horoscope for today (general, love or career) or for this week.
  • get_famous_chart Looks up the birth chart of a famous person Zodiacs publishes, and says so when it has none.
  • get_sky_calendar Gives the link to follow the Zodiacs sky calendar in Google Calendar, Apple Calendar or Outlook.
  • get_horoscope_period Shows a Sun-sign horoscope for a month, a year, or a love or career week.
  • get_chinese_zodiac Gives the Chinese zodiac animal, element and yin or yang for a birth date or a year.
  • explain_astrology Explains a basic astrology topic in plain words, with links to the Zodiacs pages it comes from.
  • open_chart_studio Opens 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_sky Describes 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_milestones Lists the Jupiter returns, Saturn returns and Uranus opposition that follow from a birth date, with dates and ages.
  • get_compatibility Compares two people’s birth charts: their signs, the closest contacts between their planets and their elements.
  • find_chart_twins Finds famous people who share your Sun sign, Moon sign or both.
  • get_birthday Describes the sky on a birthday: the Sun’s sign, its decan and whether the date falls on a cusp.
  • get_natal_chart Reads one birth chart in the conversation: Sun, Moon and rising signs, planets, houses, aspects and balance.
  • get_personal_transits Lists dated transits to your own birth chart, with what astrology traditionally reads into each.
  • find_birthplace Finds 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_calendar hands over a calendar link that you add to your own calendar app yourself.
  • get_upcoming_events does 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_birthplace returns 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.