Event timing
Muhurta Timing
find_auspicious_time
Elect a moment for one or more events by the KP four-layer test, across a real date range at the place the event happens. Layer 1 builds the significator set for the event's houses; layer 2 requires the running Dasa or Bhukti lord to be in that set; layer 3 requires the Moon to transit the star then the sub of a set member, which fixes the day and then the hours; layer 4 requires the Ascendant's sign lord, star lord AND sub lord all to be in the set, which fixes the minute. Returns ONE elected moment per event, or up to three when the selection tests genuinely cannot separate them. It is not a top ten list and there is no score: KP has no numeric strength for a moment, so candidates are compared one test at a time and the first difference decides. Returns '{ events: { eventLabel: { windows: [{ startLocal, endLocal, durationMinutes, layersSatisfied, verdict, resolvingLayer, resolvingLayerNote, dasha, moon, ascendant, matchedConditions[], exclusionsCleared[], selectionKeys, discriminator, rank }], selection, significatorSet, scanSummary, provenanceSummary, relaxations[], disclaimer } } }'. 'discriminator' says which test decided, and is printed for the winner and for any runner-up. 'resolvingLayer' says what fixed the window and therefore what its width means: an Ascendant-sub election is minutes wide, a Moon-sub election is hours wide. Do not quote a fixed window width. 'layersSatisfied' is 1 to 4 and is the longest satisfied prefix, so a 2 means the Moon layer failed and nothing below it is being claimed. 'relaxations' names any layer that had to be loosened. 'provenanceSummary' says whether the house group is quoted from the KP books or generated by the general formula, the matter's houses plus 6 and 11. Election is read-only in KP: it locates a moment the chart already points at and never causes an outcome. Say so when reporting a window. Prefer 'find_election_window' for a single event, and 'rank_candidate_dates' when the user already has dates in mind.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| birth_datetime | string | Yes | Birth date and time in ISO 8601 format (e.g., "1990-05-15T14:30:00"). |
| latitude | number | Yes | Birth location latitude. Range: -90 to 90. |
| longitude | number | Yes | Birth location longitude. Range: -180 to 180. |
| utc_offset_minutes | number | Yes | UTC offset in minutes (e.g., 330 for IST, -300 for EST). |
| ayanamsa | enum: kp | kp_new | lahiri | raman | true_chitra | khullar | No | Ayanamsa system. Defaults to kp. |
| events | array<unknown> | Yes | Events to elect for. Any label or alias from get_election_catalog, or any of the 78 natal event names. An unknown name returns a 400, it never returns an empty success. |
| scan_start | string | No | First moment to consider, ISO 8601. A bare datetime is read as local time AT THE EVENT LOCATION. Defaults to now. |
| scan_days | number | No | Days to scan. Clamped by granularity: 365 for day, 90 for hour, 30 for minute. Default 7. |
| granularity | enum: day | hour | minute | No | How precisely to elect. 'minute' runs the Ascendant layer and gives the narrowest window; 'hour' stops at the Moon sub; 'day' groups by local civil day. Defaults to the event's own default. |
| preferred_time_of_day | object | No | What this window is, for example "office hours" or "before the registrar closes". Echoed back in the response. |
| event_latitude | number | No | Latitude of where the event happens. Defaults to the birth latitude. KP computes the Ascendant for the place of the action, not the place of birth. |
| event_longitude | number | No | Longitude of where the event happens. Defaults to the birth longitude. |
| event_utc_offset_minutes | number | No | UTC offset at the event location, in minutes. Defaults to the birth offset. Drives every local time in the response. |
| max_windows | number | No | Override the default output shape and take a pool of up to 25 instead of the one elected moment. Only use this when the user explicitly asks to see the whole field. |
Example call
Send the request as a standard MCP tools/call:
POST https://mcp.lumin.guru/mcp
Authorization: Bearer mcp_yourkey...
Accept: application/json, text/event-stream
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "find_auspicious_time",
"arguments": {
"birth_datetime": "1992-08-14T04:32:00",
"latitude": 6.927,
"longitude": 79.861,
"utc_offset_minutes": 330,
"ayanamsa": "kp",
"events": []
}
}
}Birth data
This tool requires birth data on every call. The MCP server is stateless, so calling set_birth_profile first validates the data and returns the reading plan, but it does not store anything. Repeat the same five fields here.