# nocturna-mcp

MCP (Model Context Protocol) server for [Nocturna](https://nocturna.ru) 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](https://bun.sh) runtime
- Access to Nocturna API (service token required)

### Install

```bash
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:

```bash
cp .env.example .env
```

### Add to Claude Code

Add to your `.mcp.json`:

```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