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, including Claude and ChatGPT connector surfaces, can invoke.

What tools does the Electional MCP server expose?

It exposes 24 tools covering every public POST /api/v1 route, including generate_ai_guidance, expand_aspect_interpretation, calculate_daily_elections, calculate_electional_spellcasting, calculate_eclipse_hits, calculate_month_forecast_teaser, and generate_window_synthesis.

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?

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?

ChatGPT Apps and connectors can use a public HTTPS MCP endpoint. The local stdio config below is for Claude Desktop and other local MCP clients; use the REST API directly while a hosted connector is being prepared.

Is the source available?

The MCP server source lives in the Electional repo at src/mcp/index.ts. Not currently published as a standalone package — install by cloning the repo or by pointing your MCP config at npx tsx with the file path.

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 this in ChatGPT/Claude

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.
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 only when a new blend is created.
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: session_or_bearer. Credit model: 3 free IP uses per week, then 1 credit; paid overlays add credits.
calculate_daily_elections input example
```
{
  "birthDate": "1990-06-15",
  "birthTime": "14:30",
  "locationQuery": "New York, NY",
  "scanMode": "day",
  "browserNowIso": "2026-07-01T08:15:00.000-04:00",
  "browserTimezone": "America/New_York",
  "startTime": "09:00",
  "endTime": "17:00",
  "scoring": {
    "useNatalHouseFrameOnly": false
  }
}
```
- Anonymous clients get 3 free IP uses per week; valid Bearer tokens identify the account for MCP/API usage.
- 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; overlays are additive.
calculate_electional_spellcasting input example
```
{
  "intentId": "career-advancement-promotion",
  "birthDate": "1990-06-15",
  "birthTime": "14:30",
  "locationQuery": "New York, NY",
  "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.
calculate_eclipse_hits input example
```
{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "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 0 credits.
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.
calculate_month_forecast_teaser input example
```
{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "startDate": "2026-07-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: 5 credits per successful report.
calculate_month_forecast input example
```
{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "startDate": "2026-07-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": "Sagittarius",
      "moonSign": "Pisces",
      "ascSign": "Gemini"
    }
  ]
}
```
- 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.
calculate_personalized_retrograde_hits input example
```
{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "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 0 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.
calculate_solar_return input example
```
{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "referenceDate": "2026-07-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.
calculate_solar_return_location_election input example
```
{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "referenceDate": "2026-07-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.
calculate_synastry_compatibility input example
```
{
  "chartA": {
    "label": "Jordan",
    "birthDate": "1990-06-15",
    "birthTime": "14:30",
    "locationQuery": "New York, NY"
  },
  "chartB": {
    "label": "Riley",
    "birthDate": "1992-03-20",
    "birthTime": "08:15",
    "locationQuery": "Paris, France"
  },
  "orbDegrees": 3
}
```
- Both charts may be people or exactly-timed events; each needs date, time, and location.
- Every domain score ships its contributing contacts as receipts; treat bands without evidence as neutral.
- The friction domain is inverted: a high percent 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.
calculate_timeline_teaser input example
```
{
  "birthDate": "1989-12-06",
  "events": [
    {
      "id": "event-1",
      "label": "Moved cities",
      "date": "2019-07-01"
    },
    {
      "id": "event-2",
      "label": "Changed jobs",
      "date": "2021-03-10"
    }
  ]
}
```
- 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.
calculate_timeline_full_report input example
```
{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "events": [
    {
      "id": "event-1",
      "label": "Moved cities",
      "date": "2019-07-01"
    },
    {
      "id": "event-2",
      "label": "Changed jobs",
      "date": "2021-03-10"
    }
  ],
  "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 and overlays are additive.
calculate_transits input example
```
{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "startDate": "2026-07-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, plus optional add-ons.
- 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.
calculate_vedic_chart_teaser input example
```
{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "referenceDate": "2026-07-01",
  "relocationQuery": "Boulder, CO",
  "reportMode": "scored_reading"
}
```
- Free exact-birth scored reading; no Bearer token or persistence.
- 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.
calculate_vedic_chart input example
```
{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "referenceDate": "2026-07-01",
  "relocationQuery": "Boulder, CO",
  "includeVargaDeepDive": true,
  "reportMode": "scored_reading"
}
```
- Bearer token required; successful full reports cost 3 credits and auto-save to the user account.
- 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 deterministic predictive Vedic report used by the predictions route and overlays. Calls POST /api/v1/vedic-chart/predictions. Auth: free. Credit model: Free.
calculate_vedic_chart_predictions input example
```
{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "referenceDate": "2026-07-01",
  "pastEvents": [
    {
      "date": "2021-03-10",
      "label": "Changed jobs"
    }
  ],
  "includePredictive": true
}
```
- Free deterministic predictive endpoint using the same Vedic request schema.
- 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.
calculate_natal_reading_teaser input example
```
{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "referenceDate": "2026-07-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.
calculate_natal_reading input example
```
{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "referenceDate": "2026-07-01",
  "houseSystem": "P",
  "subject": "child",
  "subjectName": "Eli"
}
```
- 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.
calculate_proof_synthesis input example
```
{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "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; anonymous usage is IP-rate-limited.
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.

Quick install — Claude Desktop

Add this block to claude_desktop_config.json:

{
  "mcpServers": {
    "electional": {
      "command": "npx",
      "args": ["tsx", "/path/to/transits/src/mcp/index.ts"],
      "env": {
        "TRANSITS_API_URL": "https://electional.io",
        "TRANSITS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop. The tools appear in the tools panel. Ask Claude something like "What are the best electional windows for launching a business 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.

Sign up for an account (free, includes 10 starter credits).
Subscribe to Builder API ($49/30 days, 250 credits) or Studio API ($149/30 days, 1000 credits) for ongoing usage, or use top-ups.
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 launch a new
     business in the next 60 days? I'm born 1990-06-15 at
     14:30 in New York.

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

Claude: Top 3 windows:
  1. 2026-06-12 09:14 EDT — PRIME (76%)
     Sun trine natal Jupiter, Moon in 10th, Mercury angular...
  2. 2026-06-28 11:05 EDT — STRONG (62%)
     ...
  3. ...

Credit cost

generate_ai_guidance - 3 credits per successful guidance request.
expand_aspect_interpretation - 1 credit only when a new blend is created.
calculate_daily_elections - 3 free IP uses per week, then 1 credit; paid overlays add credits.
calculate_electional_spellcasting - 1 credit per intent per billable calendar month, times chart count; overlays are additive.
calculate_eclipse_hits - Free; public scans are capped at 10 years.
calculate_month_forecast_teaser - Free.
calculate_month_forecast - 5 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.
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.
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 and overlays are additive.
calculate_vedic_chart_teaser - Free.
calculate_vedic_chart - 3 credits per successful report.
calculate_vedic_chart_predictions - Free.
calculate_natal_reading_teaser - Free.
calculate_natal_reading - 3 credits per successful report.
calculate_proof_synthesis - Free.
generate_window_synthesis - Free; anonymous usage is IP-rate-limited.

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, including Claude and ChatGPT connector surfaces, can invoke.
What tools does the Electional MCP server expose?
It exposes 24 tools covering every public POST /api/v1 route, including generate_ai_guidance, expand_aspect_interpretation, calculate_daily_elections, calculate_electional_spellcasting, calculate_eclipse_hits, calculate_month_forecast_teaser, and generate_window_synthesis.
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?
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?
ChatGPT Apps and connectors can use a public HTTPS MCP endpoint. The local stdio config below is for Claude Desktop and other local MCP clients; use the REST API directly while a hosted connector is being prepared.
Is the source available?
The MCP server source lives in the Electional repo at src/mcp/index.ts. Not currently published as a standalone package — install by cloning the repo or by pointing your MCP config at npx tsx with the file path.

REST API docs API playground Pricing

Tools exposed

generate_ai_guidance input example

expand_aspect_interpretation input example

calculate_daily_elections input example

calculate_electional_spellcasting input example

calculate_eclipse_hits input example

calculate_month_forecast_teaser input example

calculate_month_forecast input example

generate_personality_interpretations input example

generate_placement_interpretation input example

calculate_personalized_retrograde_hits input example

calculate_solar_return input example

calculate_solar_return_location_election input example

calculate_synastry_compatibility input example

calculate_timeline_teaser input example

calculate_timeline_full_report input example

generate_transit_interpretations input example

calculate_transits input example

calculate_vedic_chart_teaser input example

calculate_vedic_chart input example

calculate_vedic_chart_predictions input example

calculate_natal_reading_teaser input example

calculate_natal_reading input example

calculate_proof_synthesis input example

generate_window_synthesis input example