EN
Free chart
Developers

Lunonis MCP server

Give an AI assistant a real astrology calculator. A free remote Model Context Protocol server that returns natal charts, synastry and birth-place matches, calculated from an ephemeris instead of recalled by a language model.

Endpoint

Add one URL to any MCP client that supports remote servers. There is no sign-in and no key, because the server is public and read-only: it calculates and returns, and cannot change anything.

Server URLhttps://lunonis.com/mcp
At a glance
Endpointhttps://lunonis.com/mcp
TransportStreamable HTTP, stateless, JSON responses (POST only; GET and DELETE return 405)
AuthenticationNone. Public and read-only
Rate limit600 requests a minute per IP; over it you get 429 with Retry-After
StorageNothing stored, no request log kept by the API
Registry namecom.lunonis/astrology

Tools

Three tools, all annotated read-only and idempotent. Each returns a short text digest followed by the full JSON, and the same JSON as structuredContent, so clients that read only text and clients that read structured output both work. A bad input or an unknown place is returned as a tool error (isError) with the reason.

natal_chart

A real natal chart: Sun, Moon and rising signs, every planet with sign, degree, retrograde flag and house, the five tightest aspects, an element and modality summary, notes and links. Tropical zodiac, Placidus houses. If the city name matches several places the result has status "ambiguous_place" and a list of candidates; ask the user, then call again with the chosen id as place.

Input

NameTypeRequiredDescription
datestringyesBirth date, YYYY-MM-DD, 1900 to 2100.
timestringnoBirth time, 24-hour HH:MM, local time. Omit it if unknown: the rising sign and houses are then left out, never guessed.
placestringyesBirth city name ("Lviv" or "Lviv, Ukraine"), or a place id from search_places. 1 to 80 characters.
langstringnoLanguage of the returned links: en, es, pt, fr, de, it, pl, tr, ja, zh or uk. Default en.

Example call (tools/call params)

{
  "name": "natal_chart",
  "arguments": { "date": "1994-02-24", "time": "08:12", "place": "Lviv" }
}

Example result

Sun in Pisces, Moon in Leo, rising Aries. Full free chart with the wheel: https://lunonis.com/chart?date=1994-02-24&time=08%3A12&place=702550&utm_source=mcp&utm_medium=ai-app&utm_campaign=lunonis-mcp

structuredContent (abridged):
{
  "birth": { "date": "1994-02-24", "time": "08:12", "place": { "id": 702550, "name": "Lviv", "region": "Lviv", "country": "UA" } },
  "bigThree": { "sun": "pisces", "moon": "leo", "rising": "aries" },
  "midheaven": "capricorn",
  "planets": [
    { "planet": "sun", "sign": "pisces", "degree": 5.4, "retrograde": false, "house": 12 },
    { "planet": "moon", "sign": "leo", "degree": 11.3, "retrograde": false, "house": 5 },
    ...
  ],
  "topAspects": [ { "between": ["venus", "jupiter"], "aspect": "trine", "orbDegrees": 0 }, ... ],
  "summary": { "dominantElement": "water", "dominantModality": "mutable", ... },
  "notes": [],
  "links": { "fullFreeChart": "https://lunonis.com/chart?...", "gift": "https://lunonis.com/gift?..." }
}

Without a time, bigThree.rising and midheaven are null, planets carry no house and notes explains why.

search_places

Birth cities by name, the biggest first, up to 6. Use it to disambiguate, then pass the id as place to the other tools.

Input

NameTypeRequiredDescription
querystringyesCity name, 2 to 80 characters.

Example call (tools/call params)

{
  "name": "search_places",
  "arguments": { "query": "Lviv" }
}

Example result

{
  "places": [ { "id": 702550, "name": "Lviv", "region": "Lviv", "country": "UA" } ]
}

compatibility

Synastry of two charts: the overall tone (flowing, mixed or charged), whether the Sun elements match, the classic pairings (Venus-Mars, Sun-Moon, Moon-Moon, Venus-Venus), the tightest Moon, Venus, Mars and Sun contacts between the charts and a link to the free comparison. Counted aspects only: there is no compatibility score.

Input

NameTypeRequiredDescription
personAobjectyes{ date, time?, place } of the first person, as in natal_chart.
personBobjectyes{ date, time?, place } of the second person.

Example call (tools/call params)

{
  "name": "compatibility",
  "arguments": {
    "personA": { "date": "1994-02-24", "time": "08:12", "place": "Lviv" },
    "personB": { "date": "1991-07-09", "place": "London" }
  }
}

Example result

{
  "people": { "a": { "sun": "pisces", "moon": "leo" }, "b": { "sun": "cancer", "moon": "gemini" } },
  "tone": "charged",
  "contactCounts": { "flow": 3, "tension": 8, "fusion": 1 },
  "sunElements": ["water", "water"],
  "elementMatch": "same",
  "pairings": { "venusMars": "opposition", "sunMoon": "square", "moonMoon": "sextile", "venusVenus": null },
  "topContacts": [ { "personA": "venus", "personB": "moon", "aspect": "square", "orbDegrees": 0.9 }, ... ],
  "notes": ["At least one birth time is unknown: that person's rising sign is left out of the contacts."],
  "links": { "fullFreeComparison": "https://lunonis.com/compatibility-calculator/result?..." }
}

Connect a client

Claude. Open Settings, then Connectors, choose Add custom connector, name it Lunonis and paste the server URL. Menu names change between versions; the feature is called custom connectors.

ChatGPT. Custom MCP connectors are available in developer mode on the plans that offer it: open the settings for apps and connectors, turn on developer mode, add a connector and paste the server URL. Without developer mode you can use the Lunonis custom GPT, which calls the same calculation through an OpenAPI action (spec).

Claude Code.

claude mcp add --transport http lunonis https://lunonis.com/mcp

Cursor. In .cursor/mcp.json (or the global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "lunonis": { "url": "https://lunonis.com/mcp" }
  }
}

VS Code. In .vscode/mcp.json:

{
  "servers": {
    "lunonis": { "type": "http", "url": "https://lunonis.com/mcp" }
  }
}

Any client or script. The server speaks JSON-RPC over HTTP POST. A quick check with curl:

curl -s https://lunonis.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_places","arguments":{"query":"Lviv"}}}'

Privacy, limits and terms

The server stores nothing: no birth details, no chart, no account, and the API keeps no request log of its own. Each request is handled on its own with no session. The links in the results point to the free chart or comparison on lunonis.com and carry the birth details in the address, as the site's own chart links do; the utm_source=mcp tags only mark where the visit came from.

Requests are limited to 600 a minute per IP address. Calls from a hosted AI service share the service's egress addresses, so if you build a product on this server and expect sustained load, write to [email protected] first. Charts are for reflection, not prediction or advice, and the availability is best effort. Use is governed by the terms of service and the privacy policy.

The server is listed in the official MCP Registry as com.lunonis/astrology. The consumer guide, for people who want their birth chart in an assistant, is at lunonis.com/ai.

Related