nocturna-mcp

MCP (Model Context Protocol) server for Nocturna astrology APIs.

Gives AI agents a full astrologer skill: natal charts, transits, synastry, progressions, returns, and chart image rendering — 20 tools total.

Tools

Calculations (via nocturna-calculations API)

Tool	Description
calculate_natal_chart	Natal (birth) chart: planets, houses, aspects
calculate_synastry	Cross-aspects between two charts
calculate_composite	Composite/Davison chart for a couple
calculate_transits	Current transits to a natal chart
calculate_progressions	Secondary progressions or solar arc
calculate_returns	Solar or lunar return chart
calculate_directions	Primary directions / solar arc directions
calculate_eclipses	Solar/lunar eclipses in a date range
calculate_ingresses	Planetary sign ingresses in a date range
calculate_fixed_stars	Fixed stars conjunct natal planets
calculate_arabic_parts	Arabic parts / lots
calculate_dignities	Essential dignities (rulership, exaltation, etc.)
calculate_antiscia	Antiscia and contra-antiscia
calculate_declinations	Declinations and parallels
calculate_harmonics	Harmonic charts
calculate_special_points	Lunar nodes, Lilith, Selena
calculate_rectification	Birth time rectification from life events

Chart Rendering (via nocturna-image API)

Tool	Description
render_natal_chart	Calculate + render natal chart as PNG
render_transit_chart	Biwheel: natal (inner) + transits (outer)
render_synastry_chart	Biwheel: person 1 (inner) + person 2 (outer)

Setup

Prerequisites

• Bun runtime
• Access to Nocturna API (service token required)

Install

git clone https://github.com/eaprelsky/nocturna-mcp
cd nocturna-mcp
bun install

Configure

Copy .env.example to .env and fill in your API tokens:

cp .env.example .env

Add to Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "nocturna": {
      "command": "bun",
      "args": ["run", "/path/to/nocturna-mcp/server.ts"],
      "env": {
        "NOCTURNA_API_URL": "https://www.calc.nocturna.ru/api",
        "NOCTURNA_SERVICE_TOKEN": "your_token",
        "CHART_SERVICE_URL": "https://www.img.nocturna.ru",
        "NOCTURNA_IMAGE_SERVICE_TOKEN": "your_image_token"
      }
    }
  }
}

Example Usage

Calculate Lady Gaga's natal chart:
→ calculate_natal_chart(date="1986-03-28", time="09:53:00", latitude=40.7128, longitude=-74.0060, timezone="America/New_York")

Render the chart as an image:
→ render_natal_chart(date="1986-03-28", time="09:53:00", latitude=40.7128, longitude=-74.0060, timezone="America/New_York", person_name="Lady Gaga")

Check transits for today:
→ calculate_transits(natal_date="1986-03-28", natal_time="09:53:00", natal_latitude=40.7128, natal_longitude=-74.0060, transit_date="2026-03-28")

License

MIT