Electional logo
3 free timing scans a week, memberships from $9/30 days, API plans from $49/30 days

FOR BUILDERS

MCP SERVER

Astrology timing tools for any MCP-compatible agent. Same Swiss Ephemeris engine as Electional, exposed through Model Context Protocol.

Why use MCP for astrology

Tools exposed

  • generate_ai_guidance

    /api/v1/ai-guidance

    Paid grounded guidance over transit, election, solar-return, or timeline payloads. Calls POST /api/v1/ai-guidance. Auth: bearer. Credit model: 3 credits per successful guidance request. Dedupes on Idempotency-Key; after a 5xx or unknown outcome, check your credit balance and retry with a NEW key.

    generate_ai_guidance input example

    {
  "domain": "election",
  "orientation": "pragmatic",
  "scope": "many",
  "items": [
    {
      "peakAtIso": "2026-07-01T16:30:00.000Z",
      "score": {
        "total": 18.4
      }
    },
    {
      "peakAtIso": "2026-07-02T18:00:00.000Z",
      "score": {
        "total": 16.9
      }
    }
  ],
  "context": {
    "intent": {
      "name": "Networking"
    }
  },
  "question": "Which window is strongest for a public launch?"
}
    • Send either item for single scope or items for many scope; the schema rejects mixing them.
    • LLM guidance is grounded against supplied route output and costs a flat 3 credits per successful request.
    • Bearer-token API clients receive raw JSON only; no saved HTML report is returned.
  • expand_aspect_interpretation

    /api/v1/aspect-interpretations/expand

    Creates or returns a permanent exact aspect/sign/house/dignity interpretation blend. Calls POST /api/v1/aspect-interpretations/expand. Auth: bearer. Credit model: 1 credit per new blend; existing blends are free. Dedupes on Idempotency-Key; after a 5xx or unknown outcome, check your credit balance and retry with a NEW key.

    expand_aspect_interpretation input example

    {
  "context": {
    "surface": "transits",
    "relationshipType": "natal_to_transit",
    "aspect": "square",
    "aspectDomain": "zodiac",
    "exactOrb": 0.42,
    "isApplying": true,
    "subject": {
      "point": "mars",
      "role": "transiting",
      "sign": "Leo",
      "house": 11,
      "dignity": "peregrine"
    },
    "object": {
      "point": "moon",
      "role": "natal",
      "sign": "Scorpio",
      "house": 3,
      "dignity": "fall"
    }
  }
}
    • The permanent cache key includes surface, relationship type, aspect domain, aspect, roles, points, signs, houses, and dignity.
    • Orb and applying or separating state are intentionally excluded from the permanent expansion key.
    • Existing blends return without another credit charge.
  • calculate_daily_elections

    /api/v1/daily-elections

    Scans all electional intents for the next 24 hours or scores one exact now chart. Calls POST /api/v1/daily-elections. Auth: ip_or_session_or_bearer. Credit model: Free: 3 runs per IP per week, no auth needed. Then 1 credit per run with a Bearer key or signed-in session; memberships with unlimited Daily Elections run free. Predictive overlays add +1 credit each, at most +3 credits per run, even for members, and need auth. secondChart (joint mode) costs 2 credits and needs auth; members run it free. Dedupes on Idempotency-Key; after a 5xx or unknown outcome, check your credit balance and retry with a NEW key.

    calculate_daily_elections input example

    {
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "scanMode": "day",
  "browserNowIso": "2026-10-01T07:15:00.000Z",
  "browserTimezone": "Europe/London",
  "startTime": "09:00",
  "endTime": "17:00",
  "scoring": {
    "useNatalHouseFrameOnly": false
  }
}
    • Free: 3 runs per IP per week, no auth needed. Then 1 credit per run with a Bearer key or signed-in session; memberships with unlimited Daily Elections run free. Predictive overlays add +1 credit each, at most +3 credits per run, even for members, and need auth. secondChart (joint mode) costs 2 credits and needs auth; members run it free.
    • Returns 402 JOINT_DAILY_AUTH_REQUIRED for an anonymous secondChart request and 402 PREDICTIVE_OVERLAY_AUTH_REQUIRED for anonymous overlays.
    • startTime and endTime narrow the scan window before scoring and cannot be used with scanMode now.
    • Results are flat and score-sorted by default; intent grouping is a UI/client concern.
  • calculate_electional_spellcasting

    /api/v1/electional-spellcasting

    Finds ranked election windows for one or many intents from one shared scan. Calls POST /api/v1/electional-spellcasting. Auth: bearer. Credit model: 1 credit per intent per billable calendar month, times chart count; predictive overlays add +1 credit each, at most +3 credits per run. Long scans may return a job receipt (jobId, statusUrl, resultUrl) instead of the finished report; call get_report_job with the jobId to fetch it.

    calculate_electional_spellcasting input example

    {
  "intentId": "career-advancement-promotion",
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "startDate": "2026-10-01",
  "rangeDays": 7,
  "strictness": "standard",
  "maxWindows": 3,
  "scoring": {
    "enabledPasses": [
      "pass1Baseline",
      "pass3IntentFit",
      "pass4NatalCompatibility"
    ],
    "useNatalHouseFrameOnly": false
  }
}
    • Credits are charged by scan length; selected paid overlays can add credits.
    • Transit-to-natal hits dominate plain transit-to-transit refinement in scoring.
    • Every window carries pass-level receipts and diagnostic context for consumer-side explanation.
  • calculate_eclipse_hits

    /api/v1/eclipse-hits

    Free exact-time natal eclipse contact checker over a capped public scan range. Calls POST /api/v1/eclipse-hits. Auth: free. Credit model: Free; public scans are capped at 10 years; anonymous callers: 20 per day per IP. A valid API key or signed-in session is not capped.

    calculate_eclipse_hits input example

    {
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "startDate": "2026-01-01",
  "endDate": "2030-12-31",
  "orbDegrees": 3
}
    • This v1 route reuses the free eclipse checker contract behind /api/free/eclipse-hits.
    • Exact birth data is required because natal angles are part of the contact set.
    • Public scan windows are capped at 10 years and charge no credits.
  • match_goal_to_intents

    /api/v1/intent-match

    Routes a plain-language goal sentence to the best 1–3 of the 72 electional intents. Calls POST /api/v1/intent-match. Auth: session_or_ip. Credit model: Free; anonymous callers: 40 per day per IP. A valid API key or signed-in session is not capped.

    match_goal_to_intents input example

    {
  "goal": "sign a lease on a new apartment"
}
    • Send only the goal sentence; names, contact details, dates, times and birth details are redacted and the text is capped at 300 characters.
    • mode is match (confidence ≥ 0.5), suggest (up to 3 lower-confidence options) or none; available is false when the classifier is off or degraded.
    • Routing never runs a scan; pass the returned intentIds to /api/v1/electional-spellcasting yourself.
  • calculate_month_forecast_teaser

    /api/v1/month

    Free exact-birth Month Ahead forecast shell without persistence. Calls POST /api/v1/month. Auth: free. Credit model: Free; anonymous callers: 20 per day per IP. A valid API key or signed-in session is not capped.

    calculate_month_forecast_teaser input example

    {
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "startDate": "2026-10-01"
}
    • Free teaser route; no Bearer token and no persistence.
    • Requires exact birth data plus startDate; defaults to a 30-day forecast when days is omitted.
    • Use the full route when the generated narrative and saved report id are required.
  • calculate_month_forecast

    /api/v1/month/full

    Paid Month Ahead report with generated narrative and auto-save. Calls POST /api/v1/month/full. Auth: bearer. Credit model: 3 credits per successful report. Dedupes on Idempotency-Key; after a 5xx or unknown outcome, check your credit balance and retry with a NEW key.

    calculate_month_forecast input example

    {
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "startDate": "2026-10-01",
  "days": 30
}
    • Bearer token required; the report is auto-saved to the API-key owner.
    • Credits are refunded on post-reservation generation or save failure.
    • The response is raw JSON; clients render their own report view.
  • generate_personality_interpretations

    /api/v1/personality-interpretation

    Batch cache endpoint for big-three, pair, and stack personality interpretation text. Calls POST /api/v1/personality-interpretation. Auth: free. Credit model: Free; cache-miss generation is IP-rate-limited.

    generate_personality_interpretations input example

    {
  "items": [
    {
      "tier": "bigthree",
      "sunSign": "Capricorn",
      "moonSign": "Leo",
      "ascSign": "Libra"
    }
  ]
}
    • Accepts up to 40 items and silently drops malformed items after normalization.
    • Cache hits are unlimited; cache-miss generation is IP-rate-limited.
    • The endpoint returns generic reusable text and does not consume credits.
  • generate_placement_interpretation

    /api/v1/placement-interpretation

    Cache endpoint for one planet/sign/house placement interpretation. Calls POST /api/v1/placement-interpretation. Auth: free. Credit model: Free; generated once per unique placement when configured.

    generate_placement_interpretation input example

    {
  "point": "venus",
  "sign": "Capricorn",
  "house": 8
}
    • One placement is generated and cached forever per point/sign/house combination.
    • No credits are charged; a missing AI configuration returns 503 on cache miss.
    • Use lowercase or display-case point/sign inputs; the route normalizes them before caching.
  • calculate_personalized_retrograde_hits

    /api/v1/retrograde-hits

    Free exact-time Mercury, Venus, and Mars retrograde contact checker. Calls POST /api/v1/retrograde-hits. Auth: free. Credit model: Free; public scans are capped at 10 years; anonymous callers: 20 per day per IP. A valid API key or signed-in session is not capped.

    calculate_personalized_retrograde_hits input example

    {
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "startDate": "2026-01-01",
  "endDate": "2030-12-31",
  "orbDegrees": 3
}
    • This v1 route reuses the free personalized retrograde checker behind /api/free/retrograde-hits.
    • Exact birth data is required because house and angle contacts are birth-time sensitive.
    • It filters to Mercury, Venus, and Mars retrograde or station-grade contacts and charges no credits.
  • calculate_solar_return

    /api/v1/solar-return

    Computes annual profection, solar-return chart context, and SR transit windows. Calls POST /api/v1/solar-return. Auth: bearer. Credit model: 1 credit per successful report. Dedupes on Idempotency-Key; after a 5xx or unknown outcome, check your credit balance and retry with a NEW key.

    calculate_solar_return input example

    {
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "referenceDate": "2026-10-01",
  "solarReturn": {
    "enabled": true,
    "returnMode": "tropical_non_precessed",
    "locationBasis": "natal"
  }
}
    • Bearer token required; costs 1 credit after validation and successful computation.
    • The endpoint always computes annual context even though the shared solarReturn option can disable scoring side effects elsewhere.
    • The natal chart remains birth-based; return-location options only frame the solar-return chart.
  • calculate_solar_return_location_election

    /api/v1/solar-return/elect-location

    Ranks birthday cities for a solar-return intent category using the curated city set. Calls POST /api/v1/solar-return/elect-location. Auth: bearer. Credit model: 3 credits per successful location election. Dedupes on Idempotency-Key; after a 5xx or unknown outcome, check your credit balance and retry with a NEW key.

    calculate_solar_return_location_election input example

    {
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "referenceDate": "2026-10-01",
  "intentCategory": "CAREER",
  "returnMode": "tropical_non_precessed",
  "topN": 10
}
    • Bearer token required; costs 3 credits per successful location election.
    • The curated city universe is population-filtered; topN may be 1 through 50.
    • Only the solar-return frame moves per candidate; the natal chart is never relocated.
  • calculate_synastry_compatibility

    /api/v1/synastry

    Domain-scored relationship compatibility (marriage, business, and more) from synastry inter-aspects, house overlays, and the composite chart. Calls POST /api/v1/synastry. Auth: bearer. Credit model: 1 credit per successful compatibility report. Dedupes on Idempotency-Key; after a 5xx or unknown outcome, check your credit balance and retry with a NEW key.

    calculate_synastry_compatibility input example

    {
  "chartA": {
    "label": "Jordan",
    "birthDate": "1990-01-01",
    "birthTime": "12:00",
    "locationQuery": "London, UK"
  },
  "chartB": {
    "label": "Riley",
    "birthDate": "1992-03-20",
    "birthTime": "08:15",
    "locationQuery": "Paris, France"
  }
}
    • Both charts may be people or exactly-timed events; each needs a date and a location. birthTime is optional: omit it when unknown and the chart is cast at noon with houses and angles skipped.
    • orbDegrees is optional. Omit it to use the calibrated per-planet orbs the bands are built on; sending it switches to a flat override (metadata.orbModel "flat_override").
    • Bands come from percentile (the rank of rawScore against the calibration table), not from percent. overall carries the verdict and its confidence.
    • Every domain score ships its contributing contacts as receipts; treat bands without evidence as neutral.
    • The friction domain is inverted: a high percentile means more friction, and its band reads accordingly.
    • The response is raw JSON and is not auto-saved.
  • calculate_timeline_teaser

    /api/v1/timeline

    Free date-only or partial timeline teaser with proof moments and hinge years. Calls POST /api/v1/timeline. Auth: free. Credit model: Free; anonymous callers: 20 per day per IP. A valid API key or signed-in session is not capped.

    calculate_timeline_teaser input example

    {
  "birthDate": "1990-01-01",
  "events": [
    {
      "id": "event-1",
      "label": "Moved cities",
      "date": "2019-07-01"
    },
    {
      "id": "event-2",
      "label": "Changed jobs",
      "date": "2021-03-10"
    },
    {
      "id": "event-3",
      "label": "Launched project",
      "date": "2024-11-20"
    }
  ]
}
    • Free and unauthenticated; accepts birthDate plus up to 5 optional dated events.
    • Date-only analysis omits angles, houses, lots, and exact-time transit windows.
    • Use the full route for exact-birth lifetime scanning and auto-save behavior.
  • calculate_timeline_full_report

    /api/v1/timeline/full

    Paid exact-time full timeline with dated-event retrodiction and auto-save. Calls POST /api/v1/timeline/full. Auth: bearer. Credit model: 3 credits per successful report. Dedupes on Idempotency-Key; after a 5xx or unknown outcome, check your credit balance and retry with a NEW key.

    calculate_timeline_full_report input example

    {
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "events": [
    {
      "id": "event-1",
      "label": "Moved cities",
      "date": "2019-07-01"
    },
    {
      "id": "event-2",
      "label": "Changed jobs",
      "date": "2021-03-10"
    },
    {
      "id": "event-3",
      "label": "Launched project",
      "date": "2024-11-20"
    }
  ],
  "eventTransitWindowDays": 30,
  "lifetimeEndDate": "2026-12-31"
}
    • Bearer token and exact birth data are required; successful reports cost 3 credits.
    • The full report auto-saves as a timeline item for the API-key owner.
    • Event and lifetime scans may be CPU-heavy; consumers should keep event counts and date ranges intentional.
  • generate_transit_interpretations

    /api/v1/transit-interpretation

    Batch cache endpoint for generic transit-to-natal interpretation text. Calls POST /api/v1/transit-interpretation. Auth: free. Credit model: Free; generated once per unique transit pattern when configured.

    generate_transit_interpretations input example

    {
  "items": [
    {
      "transitingPoint": "jupiter",
      "aspect": "trine",
      "natalPoint": "sun",
      "natalHouse": 10,
      "transitingSign": "Cancer",
      "natalSign": "Pisces"
    }
  ]
}
    • Accepts up to 40 items and dedupes by the normalized transit interpretation key.
    • Malformed items are skipped; an empty normalized set returns an empty interpretations array.
    • This generic cache endpoint is free and separate from paid aspect-tooltip expansions.
  • calculate_transits

    /api/v1/transits

    Calculates natal-to-transit and optional transit-to-transit aspect hits. Calls POST /api/v1/transits. Auth: bearer. Credit model: 1 credit per billable calendar month, times chart count; transit-to-transit adds +1 credit and predictive overlays add +1 credit each, at most +3 credits per run. Long scans may return a job receipt (jobId, statusUrl, resultUrl) instead of the finished report; call get_report_job with the jobId to fetch it.

    calculate_transits input example

    {
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "startDate": "2026-10-01",
  "rangeDays": 14,
  "transitToTransit": true,
  "transitingPoints": [
    "jupiter",
    "saturn",
    "chiron"
  ],
  "aspects": [
    "conjunction",
    "trine",
    "opposition"
  ]
}
    • Bearer token required; charges 1 credit per billable calendar month, times chart count; transit-to-transit adds +1 credit and predictive overlays add +1 credit each, at most +3 credits per run.
    • Provide either locationQuery or latitude plus longitude; relocation settings affect transit frame only.
    • Each transit hit includes enter/exact/exit ISO timestamps when a span can be resolved.
    • Optional secondChart (person or event) scans the second and composite charts too (monthly base credits ×3) and returns chartResults plus a synastry relationship compatibility report.
  • calculate_vedic_chart_teaser

    /api/v1/vedic-chart

    Free exact-birth Vedic scored reading with frame comparison and predictive timing. Calls POST /api/v1/vedic-chart. Auth: free. Credit model: Free; anonymous callers: 20 per day per IP. A valid API key or signed-in session is not capped.

    calculate_vedic_chart_teaser input example

    {
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "referenceDate": "2026-10-01",
  "relocationQuery": "Paris, France",
  "reportMode": "scored_reading"
}
    • Free exact-birth scored reading; no Bearer token or persistence.
    • The response is { metadata, report }: domains, dasha, nakshatras and vargas live under report.
    • Public copy should call this Vedic Chart, not True Signs.
    • The contract distinguishes Western tropical, Tropical Vedic, and Lahiri sidereal comparison frames.
  • calculate_vedic_chart

    /api/v1/vedic-chart/full

    Paid full Vedic Chart report with saved scored reading and deep technical sections. Calls POST /api/v1/vedic-chart/full. Auth: bearer. Credit model: 3 credits per successful report. Dedupes on Idempotency-Key; after a 5xx or unknown outcome, check your credit balance and retry with a NEW key.

    calculate_vedic_chart input example

    {
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "referenceDate": "2026-10-01",
  "relocationQuery": "Paris, France",
  "includeVargaDeepDive": true,
  "reportMode": "scored_reading"
}
    • Bearer token required; successful full reports cost 3 credits and auto-save to the user account.
    • The response is { metadata, report, vargaDeepDives }; vargaDeepDives carries all sixteen evaluated Shodashavarga readings with receipted findings.
    • Use includeVargaDeepDive when the consumer needs technical varga sections.
    • The response is raw JSON and preserves the frame-comparison evidence rather than returning HTML.
  • calculate_vedic_chart_predictions

    /api/v1/vedic-chart/predictions

    Free Vedic predictive report (includes an AI synthesis step) used by the predictions route and overlays. Calls POST /api/v1/vedic-chart/predictions. Auth: free. Credit model: Free; anonymous callers: 5 per day per IP. A valid API key or signed-in session is not capped.

    calculate_vedic_chart_predictions input example

    {
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "referenceDate": "2026-10-01",
  "pastEvents": [
    {
      "date": "2021-03-10",
      "label": "Changed jobs"
    }
  ],
  "includePredictive": true
}
    • Free predictive endpoint using the same Vedic request schema; each report includes an AI synthesis step, so anonymous use has a tighter daily cap.
    • Past events are optional and capped at 5; they are used as retrodictive calibration evidence.
    • This endpoint is for JSON consumers and overlays, not the public Vedic Chart landing copy.
  • calculate_natal_reading_teaser

    /api/v1/natal-reading

    Free exact-birth natal reading teaser: placements, top tensions, one growth lever, and a child/parenting mode. Calls POST /api/v1/natal-reading. Auth: free. Credit model: Free; anonymous callers: 20 per day per IP. A valid API key or signed-in session is not capped.

    calculate_natal_reading_teaser input example

    {
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "referenceDate": "2026-10-01",
  "houseSystem": "P",
  "subject": "self",
  "includeLilith": true
}
    • Free, no bearer token: requires exact birth date, time, and place (city query or latitude/longitude).
    • subject "child" switches to parenting mode: tendencies, what helps, what backfires; romance, sexuality, and career-legacy domains are never named for minors.
    • Teaser responses are trimmed (top 3 tensions, one growth lever, empty aspect inventory, no house-frame table or midpoints); use /api/v1/natal-reading/full for the complete reading.
    • Every interpretive item carries a receipt such as "Venus ♋ 4th □ Saturn ♈ 1st, 1.8°"; tensions surface only within 6 degrees in exact/tight/moderate tiers.
  • calculate_natal_reading

    /api/v1/natal-reading/full

    Paid full natal reading with every tension's pair-specific reading, full aspect inventory, growth plan, Vedic lens, house-frame comparison, midpoints, grounded AI narrative, and auto-save. Calls POST /api/v1/natal-reading/full. Auth: bearer. Credit model: 3 credits per successful report. Dedupes on Idempotency-Key; after a 5xx or unknown outcome, check your credit balance and retry with a NEW key.

    calculate_natal_reading input example

    {
  "birthDate": "2019-03-14",
  "birthTime": "06:42",
  "locationQuery": "London, UK",
  "subjectName": "Sam",
  "referenceDate": "2026-10-01",
  "houseSystem": "P",
  "subject": "child"
}
    • Bearer token required; successful full reports cost 3 credits, auto-save as a natal_reading item, and refund on failure.
    • aiNarrative is nullable: the deterministic report always ships and the grounded narrative degrades to null when the provider is down or the output stays ungrounded.
    • The session equivalent is POST /api/calculations/natal-reading (durable report job); this route returns the finished JSON synchronously.
  • calculate_proof_synthesis

    /api/v1/proof-synthesis

    Free cross-system life-guess synthesis: combines Timeline dated cycles with Vedic domain scores into concrete, window-level, falsifiable life guesses. Calls POST /api/v1/proof-synthesis. Auth: free. Credit model: Free; anonymous callers get 5 full reads per week per network, then the deterministic checks only. Signed-in users are not capped.

    calculate_proof_synthesis input example

    {
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "houseSystem": "P"
}
    • Free, no bearer token: requires exact birth date, time, and place; reuses the Vedic chart request schema.
    • Combines Timeline dated cycles and Vedic domain scores into concrete, window-level, falsifiable life guesses.
    • Guesses are window-level only; the deterministic evidence bundle always ships and the AI guess layer degrades to an empty list when the provider is down.
    • Optional streaming: send `Accept: application/x-ndjson` to receive two NDJSON events — `{type:"evidence"}` (deterministic report, fast) then `{type:"complete"}` (full report with AI guesses). Default JSON behavior is unchanged.
  • generate_window_synthesis

    /api/v1/window-synthesis

    Free grounded synthesis over rendered election, transit, Vedic, synastry, or natal reading result items. Calls POST /api/v1/window-synthesis. Auth: session_or_ip. Credit model: Free; per domain, anonymous callers get 10 per week per IP, signed-in accounts 25 per week, and members are unlimited.

    generate_window_synthesis input example

    {
  "domain": "election",
  "orientation": "pragmatic",
  "items": [
    {
      "intentName": "Networking",
      "peakAtIso": "2026-07-01T15:20:00.000Z",
      "score": {
        "total": 18.24
      }
    }
  ],
  "context": {
    "route": "/today"
  }
}
    • Accepts election, transits, vedic, synastry, or natal domains and up to 96 items after truncation.
    • Anonymous usage is IP-rate-limited; signed-in users bypass the weekly anonymous cap.
    • Failures degrade to synthesis null so clients should keep deterministic fallback copy.
  • get_report_job

    /api/v1/report-jobs/{jobId}

    Checks a durable report job by jobId and, once it has completed, returns the finished report. Use it when calculate_transits or calculate_electional_spellcasting returns a job receipt (jobId, statusUrl, resultUrl) instead of a report. Calls GET /api/v1/report-jobs/{jobId}, then GET /api/v1/report-jobs/{jobId}/result when the status is completed. While the job is created, queued, running or retry_wait it returns the status; call it again after a few seconds. Auth: bearer. Credit model: Free; the report's credits were reserved when the job was created.

    get_report_job input example

    {
  "jobId": "6650f1c2a9e4b3d2c1f0e9a8"
}
    • Returns the job status while it is created, queued, running or retry_wait; call again after a few seconds.
    • Once the status is completed it also returns the finished report from /result.
    • Failed or rejected jobs come back as a tool error with the job's failure code.

Install — Claude Desktop

MCP access is in private beta. The server runs locally and is not yet a public package, so email sales@electional.io for the package. The REST API is the supported path today.

Once you have the package, add this block to claude_desktop_config.json, with the absolute path to its src/mcp/index.ts:

{
  "mcpServers": {
    "electional": {
      "command": "npx",
      "args": [
        "tsx",
        "/ABSOLUTE/PATH/TO/electional-mcp/src/mcp/index.ts"
      ],
      "env": {
        "TRANSITS_API_URL": "https://electional.io",
        "TRANSITS_API_KEY": "sk_tr_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. The tools appear in the tools panel. Ask Claude something like "What are the best windows to ask for a promotion in the next 60 days for my chart?" and it'll call the MCP server.

Get an API key

The MCP server is a thin client over Electional's REST API. You need an API key to use it.

  1. Sign up for an account (free, includes 10 starter credits).
  2. Subscribe to Builder API ($49/30 days, 250 credits) or Studio API ($149/30 days, 1,000 credits) for ongoing usage, or use top-ups.
  3. After verified checkout, continue to the explicit key-creation step at /api-keys. No key is created or charged automatically.

Example: ask Claude

You: When are the strongest windows for me to ask for a
     promotion in the next 60 days? I was born 1990-01-01 at
     12:00 in London, UK.

Claude: [calls calculate_electional_spellcasting with
        intentId: "career-advancement-promotion", birthDate,
        birthTime, locationQuery, rangeDays: 60]

        A 60-day scan takes longer than the call waits, so the
        tool returns a job receipt: { jobId, status: "queued",
        statusUrl, resultUrl }.

Claude: [calls get_report_job with the jobId until the
        status is "completed"; the last call returns the report]

Claude: Top 2 windows:
  1. <date and time> — PRIME
     <the contacts that support it>
  2. <date and time> — STRONG
     ...

Credit cost

  • generate_ai_guidance - 3 credits per successful guidance request.
  • expand_aspect_interpretation - 1 credit per new blend; existing blends are free.
  • calculate_daily_elections - Free: 3 runs per IP per week, no auth needed. Then 1 credit per run with a Bearer key or signed-in session; memberships with unlimited Daily Elections run free. Predictive overlays add +1 credit each, at most +3 credits per run, even for members, and need auth. secondChart (joint mode) costs 2 credits and needs auth; members run it free.
  • calculate_electional_spellcasting - 1 credit per intent per billable calendar month, times chart count; predictive overlays add +1 credit each, at most +3 credits per run.
  • calculate_eclipse_hits - Free; public scans are capped at 10 years; anonymous callers: 20 per day per IP. A valid API key or signed-in session is not capped.
  • match_goal_to_intents - Free; anonymous callers: 40 per day per IP. A valid API key or signed-in session is not capped.
  • calculate_month_forecast_teaser - Free; anonymous callers: 20 per day per IP. A valid API key or signed-in session is not capped.
  • calculate_month_forecast - 3 credits per successful report.
  • generate_personality_interpretations - Free; cache-miss generation is IP-rate-limited.
  • generate_placement_interpretation - Free; generated once per unique placement when configured.
  • calculate_personalized_retrograde_hits - Free; public scans are capped at 10 years; anonymous callers: 20 per day per IP. A valid API key or signed-in session is not capped.
  • calculate_solar_return - 1 credit per successful report.
  • calculate_solar_return_location_election - 3 credits per successful location election.
  • calculate_synastry_compatibility - 1 credit per successful compatibility report.
  • calculate_timeline_teaser - Free; anonymous callers: 20 per day per IP. A valid API key or signed-in session is not capped.
  • calculate_timeline_full_report - 3 credits per successful report.
  • generate_transit_interpretations - Free; generated once per unique transit pattern when configured.
  • calculate_transits - 1 credit per billable calendar month, times chart count; transit-to-transit adds +1 credit and predictive overlays add +1 credit each, at most +3 credits per run.
  • calculate_vedic_chart_teaser - Free; anonymous callers: 20 per day per IP. A valid API key or signed-in session is not capped.
  • calculate_vedic_chart - 3 credits per successful report.
  • calculate_vedic_chart_predictions - Free; anonymous callers: 5 per day per IP. A valid API key or signed-in session is not capped.
  • calculate_natal_reading_teaser - Free; anonymous callers: 20 per day per IP. A valid API key or signed-in session is not capped.
  • calculate_natal_reading - 3 credits per successful report.
  • calculate_proof_synthesis - Free; anonymous callers get 5 full reads per week per network, then the deterministic checks only. Signed-in users are not capped.
  • generate_window_synthesis - Free; per domain, anonymous callers get 10 per week per IP, signed-in accounts 25 per week, and members are unlimited.
  • get_report_job- Free; the report's credits were reserved when its job was created.

FAQ

  • What is MCP?

    Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools through a uniform interface. An MCP server exposes one or more tools that MCP-compatible clients, such as Claude Desktop and Claude Code, can invoke.

  • What tools does the Electional MCP server expose?

    It exposes 26 tools: one for every public POST /api/v1 route, including generate_ai_guidance, expand_aspect_interpretation, calculate_daily_elections, calculate_electional_spellcasting, calculate_eclipse_hits, match_goal_to_intents, and generate_window_synthesis, plus get_report_job, which fetches a long transit or electional report by its job id.

  • Does using the MCP server consume API credits?

    Yes. The MCP server is a thin client that calls Electional's REST API on your behalf. Same credit cost as direct API calls. You need a TRANSITS_API_KEY environment variable.

  • How do I install it in Claude Desktop?

    Once you have the package, add the Electional server block to your claude_desktop_config.json with your API key. Full config snippet below.

  • Can I use it from ChatGPT?

    Today the server runs locally over stdio, so it works in Claude Desktop, Claude Code and other local MCP clients. ChatGPT and the Claude API need a hosted HTTPS endpoint, which we don't offer yet; call the REST API instead.

  • How do I get the server?

    MCP access is in private beta. The server runs locally and is not yet a public package, so email sales@electional.io for the package. The REST API is the supported path today.

REST API docsAPI playgroundPricing