natalengine

NatalEngine

Birth chart calculation engine for Western Astrology, Human Design, and Gene Keys.

Returns clean, structured data for apps and AI integrations. No interpretation, just the facts.

Install

npm install natalengine

Quick Start

import {
  calculateAstrology,
  calculateHumanDesign,
  calculateGeneKeys
} from 'natalengine';

// Western Astrology
const astro = calculateAstrology('1990-06-15', 14.5, -5, 40.7128, -74.0060);
console.log(astro.sun.sign.name);        // "Gemini"
console.log(astro.moon.sign.name);       // "Pisces"
console.log(astro.rising.sign.name);     // "Libra"
console.log(astro.planets.venus.degree); // "19°08'41\""

// Human Design
const hd = calculateHumanDesign('1990-06-15', 14.5, -5);
console.log(hd.type.name);               // "Manifestor"
console.log(hd.authority.name);          // "Emotional Authority"
console.log(hd.profile.numbers);         // "2/4"
console.log(hd.channels);                // [{ gates: [12, 22], name: "..." }]

// Gene Keys
const gk = calculateGeneKeys(hd);
console.log(gk.activationSequence.lifeWork.gift);  // "Discrimination"
console.log(gk.activationSequence.lifeWork.shadow); // "Vanity"
console.log(gk.activationSequence.lifeWork.siddhi); // "Purity"

API

calculateAstrology(birthDate, birthHour, timezone, latitude?, longitude?)

Returns Western natal chart data.

Parameter	Type	Description
birthDate	string	YYYY-MM-DD format
birthHour	number	Decimal hours (14.5 = 2:30 PM)
timezone	number	UTC offset (-5 for EST)
latitude	number	Optional. Required for accurate Rising sign
longitude	number	Optional. Required for accurate Rising sign

Returns:

{
  sun: { sign, degree, longitude },
  moon: { sign, degree, longitude },
  rising: { sign, degree, longitude, accurate },
  planets: {
    mercury: { sign, degree, longitude },
    venus: { sign, degree, longitude },
    mars: { sign, degree, longitude },
    jupiter: { sign, degree, longitude },
    saturn: { sign, degree, longitude },
    uranus: { sign, degree, longitude },
    neptune: { sign, degree, longitude },
    pluto: { sign, degree, longitude }
  },
  nodes: {
    north: { sign, degree, longitude },
    south: { sign, degree, longitude }
  },
  midheaven: { sign, degree, longitude },
  aspects: [
    { planet1, planet2, aspect, orb, applying }
  ],
  balance: {
    elements: { fire, earth, air, water },
    modalities: { cardinal, fixed, mutable },
    dominantElement,
    dominantModality
  }
}

calculateHumanDesign(birthDate, birthHour, timezone)

Returns Human Design chart data.

Returns:

{
  type: { name, strategy, authority, notSelf, signature },
  authority: { name, description },
  profile: { numbers, name, theme },
  definition: "Single Definition" | "Split Definition" | "Triple Split" | "Quadruple Split",
  incarnationCross: { name, gates, theme },
  centers: {
    defined: [{ name, theme, biological }],
    undefined: [{ name, theme, biological }],
    definedNames: ["Sacral", "Throat", ...],
    undefinedNames: ["Head", "Ajna", ...]
  },
  gates: {
    personality: { sun, earth, moon, northNode, southNode, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto },
    design: { sun, earth, moon, northNode, southNode, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto },
    all: [1, 2, 3, ...]
  },
  channels: [{ gates, name, centers }],
  positions: {
    personality: { date, sun, earth, moon, ... }, // Raw planetary data at birth
    design: { date, sun, earth, moon, ... }       // Raw planetary data 88° before
  }
}

calculateGeneKeys(humanDesignData)

Returns Gene Keys profile from Human Design data.

Returns:

{
  activationSequence: {
    lifeWork: { key, line, keyLine, shadow, gift, siddhi },
    evolution: { key, line, keyLine, shadow, gift, siddhi },
    radiance: { key, line, keyLine, shadow, gift, siddhi },
    purpose: { key, line, keyLine, shadow, gift, siddhi }
  },
  venusSequence: {
    attraction: { key, line, keyLine, shadow, gift, siddhi },
    iq: { key, line, keyLine, shadow, gift, siddhi },
    eq: { key, line, keyLine, shadow, gift, siddhi },
    sq: { key, line, keyLine, shadow, gift, siddhi }
  },
  pearlSequence: {
    vocation: { key, line, keyLine, shadow, gift, siddhi },
    culture: { key, line, keyLine, shadow, gift, siddhi },
    pearl: { key, line, keyLine, shadow, gift, siddhi }
  },
  core: { ... },       // Same as vocation (Design Mars) - Venus Sequence lens
  brand: { ... },      // Same as lifeWork (Personality Sun) - Pearl Sequence lens
  allKeys: [...],      // All 11 Gene Keys in the profile
  primeGifts: [...],   // The 4 gifts from Activation Sequence
  summary: "Life's Work: 64.3 (Imagination), ..."
}

MCP Server (AI Integration)

NatalEngine includes an MCP server for Claude and other AI assistants.

Usage with Claude Code

Add to your Claude Code settings (~/.claude/settings.json):

{
  "mcpServers": {
    "natalengine": {
      "command": "npx",
      "args": ["natalengine-mcp"]
    }
  }
}

Then ask Claude:

"Calculate my birth chart for June 15, 1990 at 2:30 PM in New York"

Available Tools

Tool	Description
calculate_natal_chart	Complete profile (all 3 systems)
calculate_astrology	Western natal chart
calculate_human_design	Human Design chart
calculate_gene_keys	Gene Keys profile
get_planetary_positions	Raw planetary longitudes

Accuracy

• Planetary positions: VSOP87 via astronomy-engine
• Accuracy: ±1 arcminute
• Ascendant: Calculated from local sidereal time
• Human Design: 88° solar arc for design calculation

What's Included

System	Data
Astrology	Sun, Moon, Rising, all planets, nodes, midheaven, aspects, elements, modalities
Human Design	Type, Strategy, Authority, Profile, Centers, Gates (13 planets), Channels, Incarnation Cross
Gene Keys	Activation Sequence, Venus Sequence, Pearl Sequence with shadow/gift/siddhi

What's NOT Included

• Interpretations or readings
• Transit calculations
• Synastry/compatibility (coming soon)
• Progressed charts
• Solar returns

License

MIT