ask-ollama

Ask Ollama

Send a prompt to a local Ollama LLM (defaults to qwen3.6:27b; errors with a 'pull it first' message if the model isn't installed — no automatic substitution). Use for code review, second opinions, analysis, and AI-to-AI collaboration. Runs entirely locally — no API keys or network calls needed. Returns both human-readable text and a structured response (provider, model, sessionId, usage) via outputSchema.

DO NOT set this parameter unless the user explicitly requests a specific model. The tool uses qwen3.6:27b by default; if the model isn't pulled locally it returns a clear "ollama pull" error rather than substituting another model.

The question, code review request, or analysis task to send to Ollama

Optional session ID for multi-turn conversations. Pass an empty string to start a new session (the response will include the new ID); pass a previous [Session ID: ...] value to continue the same chat. Conversation history is stored in /tmp/ask-llm-sessions/ for 24h.

gemini codex claude grok ollama antigravity

get-usage-stats

Get Usage Stats

Get the current MCP server's session usage stats: total LLM calls, token totals (input/output/thinking/cached), wall time, and breakdowns per provider and per model. No data leaves your machine — counts are tracked in-memory for the lifetime of the server process. Returns both human-readable markdown and a structured JSON snapshot via outputSchema.

calls inputTokens outputTokens cachedTokens thinkingTokens durationMs fellBack

totalCalls totalInputTokens totalOutputTokens totalCachedTokens totalThinkingTokens totalDurationMs fallbackCount byProvider byModel

ping

Ping

Test connectivity with the Ollama MCP server and list locally available models

A message to echo back to test the connection


Build an item in Jenkins.

Cancel a specific item in Jenkins queue by id.

Get all items from Jenkins.

Get all nodes from Jenkins.

Get all items in Jenkins queue.

Get specific build info from Jenkins.

Read incremental console output from a specific byte offset.

Get the tail of a specific build console output.

Get focused failure excerpts and failing tests via incremental log scanning.

Get scripts used in a specific build.

Get test report of a specific build.

Get specific item from Jenkins.

Get specific item config from Jenkins.

Get a specific node from Jenkins.

Get node config from Jenkins.

Get a specific item in Jenkins queue by id.

Get all running builds from Jenkins.

Query items from Jenkins.

Search build console output incrementally and return matching excerpts.

Set specific item config in Jenkins.

Set specific node config in Jenkins.

Stop a specific build.


ask-cursor-agent

Ask via Cursor Agent

Use Cursor Agent as a model-neutral, read-only consultation harness. The provider and exact Cursor catalog model ID are separate required fields. Runs `agent --print --mode ask` without --force/--trust, never changes spend settings, and never falls back to another model or provider.

Relative additional workspace directories passed to Cursor Agent with repeatable --add-dir.

Exact Cursor catalog model ID from `agent --list-models`; Ask LLM does not rewrite it, echoes it back as `model`, and refuses Auto or other noncanonical IDs. The CLI's display label is returned separately as `reportedModel`.

Question, review, or analysis task for Cursor Agent ask mode.

Canonical provider family of the selected Cursor model (claude, codex, gemini, grok); kept separate from the cursor-agent harness and verified against the requested and CLI-reported model ID.

Prior Cursor conversation ID to resume. Omit on the first call and reuse the returned sessionId.

ask-llm

Ask LLM

Send a prompt to an LLM provider (Codex, Claude, Grok, Antigravity, Ollama, Gemini). Specify which provider to use. Provider-specific fallback behavior is reported truthfully; Grok never substitutes or falls back from the requested model. Returns both human-readable text and a structured response (provider, model, sessionId, usage) via outputSchema.

Execution harness, separate from provider/model. xai-api and grok-cli require provider=grok. Use ask-cursor-agent for Cursor's model-neutral harness. No harness fallback is attempted.

Relative workspace directories exposed to providers that support additional read roots (Codex, Claude, and Antigravity). Unsupported providers are rejected instead of silently dropping this option; Codex only accepts it on a fresh call (sessionId omitted or ""), never on a resumed thread.

Exact model ID for the selected provider/harness. Usually not needed.

The question, code review request, or analysis task to send

Which LLM provider to use. Available: "gemini" (Gemini, default model: gemini-3.1-pro-preview), "codex" (Codex, default model: gpt-5.6-sol), "claude" (Claude, default model: opus), "grok" (Grok, default model: grok-4.6), "ollama" (Ollama, default model: qwen3.6:27b), "antigravity" (Antigravity, default model: gemini-3.1-pro)

Provider-native reasoning effort. Codex accepts low/medium/high/xhigh/max; Grok accepts low/medium/high/xhigh. Unsupported provider/effort combinations are rejected, never stripped.

Optional session ID. For Codex, pass "" on the first call to create a persisted thread, then pass its returned Thread ID to resume; omitting it makes the call ephemeral. For other session-capable providers, pass a prior Session ID to resume. Claude/Gemini use --resume, Codex uses exec resume, and Ollama uses server-side replay. Grok and Antigravity are one-shot.

diagnose

Diagnose Environment

Run a self-diagnosis of the MCP server's environment: Node version, resolved PATH, provider CLI presence and versions, key env vars. Returns a structured report and a human-readable summary. Read-only; never spawns LLM calls.

nodeVersion nodeOk platform arch resolvedPath timeoutMs codexTimeoutMs claudeTimeoutMs geminiTimeoutMs grokTimeoutMs cursorHarnessTimeoutMs

status generatedAt environment providers checks

get-usage-stats

Get Usage Stats

Get the current MCP server's session usage stats: total LLM calls, token totals (input/output/thinking/cached), wall time, and breakdowns per provider and per model. No data leaves your machine — counts are tracked in-memory for the lifetime of the server process. Returns both human-readable markdown and a structured JSON snapshot via outputSchema.

multi-llm

Multi-LLM Parallel Dispatch

Dispatch the same prompt to multiple LLM providers in parallel and return all responses in one structured payload. Use when you want to compare answers across Codex, Claude, Grok, Antigravity, Ollama, and Gemini, or when you want a multi-provider sanity check on a question. Returns per-provider success/failure, response text, model, sessionId, and token usage. Each call is fresh — no session continuity (use ask-llm for individual session-bearing calls).

The prompt to send to all selected providers in parallel.

Which providers to dispatch to. Available: gemini, codex, claude, grok, ollama, antigravity. Defaults to all available providers.

dispatchedAt totalDurationMs successCount failureCount results

ping

Ping

Test connectivity with the MCP server

A message to echo back to test the connection


Re-authenticate against Ara using the credentials configured in this server's environment, and report the current authentication state.

Takes no arguments on purpose: credentials must never be passed as tool arguments, because tool arguments transit through the model's context and are persisted in conversation transcripts.

Configure them in the `env` block of your MCP client configuration:
- ARA_AUTH_TOKEN — a pre-issued Bearer token (recommended)
- ARA_USERNAME + ARA_PASSWORD — used to sign in automatically at startup

Use this tool only when a call has failed with an expired-token error.

Refresh the Ara session

Create a new RGAA accessibility audit in Ara. Returns the audit with its editUniqueId (for editing) and consultUniqueId (for viewing the report).

Audit types:
- FULL: all 106 RGAA criteria
- FAST: 25 criteria (audit rapide)
- COMPLEMENTARY: 25 criteria (audit complémentaire) — disjoint from the rapid ones, the two methodologies together covering 50

Call list_rgaa_criteria to see exactly which criteria a type covers.

Type of RGAA audit

Email of the auditor. Required: the Ara API answers 500 Internal Server Error when it is missing, even though it does not list the field as mandatory.

Name of the auditor

Types of elements present on the site

Site contains form elements

Site contains iframes

Site contains multimedia elements

Site contains data tables

List of pages to audit

Page name (e.g. 'Page d'accueil')

Page URL

Name of the audited procedure/site

auditType procedureName pages auditorName auditorEmail pageElements

Create an RGAA audit

Soft-delete an audit. The audit itself returns HTTP 410 Gone for future requests, and disappears from the account's audit list. This cannot be undone from this server.

IMPORTANT — deleting does NOT unpublish. If the audit was published, its report REMAINS publicly readable at its consultation URL after deletion, and it is then reachable from nowhere in the Ara interface, so it can no longer be edited or withdrawn. Verified against the live API. Do not present deletion to the user as a way to undo a publication.

The editUniqueId of the audit to delete

Delete an audit

Fully duplicate an existing audit (metadata, pages, RGAA results, example images). Returns a new audit with fresh IDs. The source audit is left untouched.

Name for the duplicated audit

The editUniqueId of the audit to duplicate

Duplicate an audit

Export audit results in CSV format.

The editUniqueId of the audit

Export results as CSV

Retrieve a full audit by its editUniqueId. Returns all metadata, pages, environments, and notes.

The editUniqueId of the audit

Get an audit

Return the work plan for an audit type: which criteria can be settled by reading the HTML source, and which ones require the rendered page, keyboard navigation, the accessibility tree, or editorial judgement.

Call this BEFORE starting an audit. It tells you which tools you will actually need — a browser, a keyboard pass, a screen reader — instead of discovering halfway through that half the criteria cannot be answered from markup.

Criteria that need more than the source cannot be marked COMPLIANT or NOT_COMPLIANT by update_audit_results without declaring the matching evidence.

This classification is guidance from this server, not a prescription of the RGAA.

The Ara audit type you are about to run

Plan de travail d'un audit

Where an audit stands: how many criteria are evaluated on each page, and WHICH ONES ARE LEFT — as a compact list of ids.

Use this instead of get_audit_results whenever the question is "what remains to be done". A FULL audit carries 106 criteria per page, transverse elements included: 212 results for a single page, close to a thousand on an eight-page sample. Pulling all of them back just to spot the gaps wastes the context you need for the audit itself.

Also reports whether the audit can be published — Ara refuses publish_audit while a single criterion is still NOT_TESTED, and this is how you find that one.

The editUniqueId of the audit

Avancement d'un audit

Retrieve all criterion results for an audit. Returns an array of results, each with:
- topic (1-13): RGAA topic number
- criterium: criterion number within the topic
- pageId: ID of the audited page
- status: COMPLIANT | NOT_COMPLIANT | NOT_APPLICABLE | NOT_TESTED
- compliantComment / notApplicableComment
- notCompliantItems: the individual issues found, each with title, comment, userImpact (MINOR | MAJOR | BLOCKING) and quickWin

On a FULL audit this returns 106 criteria per page — hundreds of entries. Filter by pageId or status rather than pulling everything, and call get_audit_progress when all you need is what is left to evaluate.

Keep only this page. Page ids come from get_audit.

Keep only results in this state

The editUniqueId of the audit

Get all criterion results

Get the full audit report (read-only). Includes accessibility rate, criteria counts, and result distributions by page and topic. Uses the consultUniqueId (not the editUniqueId).

The consultUniqueId of the audit (found in the audit data)

Get the audit report

Return the wording of a single RGAA 4.1 criterion AND its numbered tests — the checks an auditor actually performs to decide COMPLIANT / NOT_COMPLIANT / NOT_APPLICABLE.

Call this before evaluating a criterion with update_audit_results: it is what turns "topic 6, criterium 1" into something you can actually assess. Also tells whether the criterion belongs to the rapid or complementary audit.

The "verification" block says what is needed BEYOND the HTML source to settle the criterion — keyboard navigation, rendered page, accessibility tree, or editorial judgement — and how to go about it. When "sourceSuffit" is false, reading the markup is not enough: open the page.

Source: the RGAA reference shipped with Ara, published by the DINUM under Licence Ouverte 2.0.

Criterion number within the topic

RGAA topic number (1-13)

Get one RGAA criterion and its tests

List RGAA 4.1 criteria as an index: topic number, topic name, criterion number and wording. Tests are NOT included — call get_rgaa_criterion for those.

Use this to know what an audit actually covers before evaluating anything. Filter to keep the answer small:
- auditType FAST — the 25 criteria of a rapid audit
- auditType COMPLEMENTARY — the 25 complementary criteria (disjoint from the rapid ones)
- auditType FULL, or no filter — all 106
- topic — restrict to one of the 13 topics

Source: the RGAA reference shipped with Ara, published by the DINUM under Licence Ouverte 2.0.

Keep only the criteria covered by this Ara audit type

Keep only this RGAA topic (1-13)

List the RGAA criteria

Update only the notes field of an audit, without touching other metadata. The new content REPLACES the existing notes.

Unlike criterion comments, this field is passed through as rich text: HTML is interpreted. Write <th> rather than <th> if you need to quote markup literally.

New notes content (rich text / HTML)

The editUniqueId of the audit

Replace the audit notes

Mark an audit as published/completed. This makes the audit report and its accessibility statement PUBLICLY available at their consultation URL — confirm with the user before calling it. The audit must be fully filled in (all criteria evaluated) before publishing. Returns HTTP 409 if incomplete.

IMPORTANT — publishing is effectively irreversible from here. There is no unpublish operation, and delete_audit does NOT withdraw a published report: it stays publicly readable while disappearing from the Ara interface. Make sure the user means to publish THIS audit, on THIS site, before calling it — publishing an audit about a third party puts a public accessibility statement about them under the auditor's name.

The editUniqueId of the audit to publish

Publish an audit (public)

Full update of an audit's metadata (procedure info, auditor info, environments, tools, technologies, notes, etc.). This REPLACES the existing metadata: fetch the audit with get_audit first and resend the fields you want to keep.

Accessibility contact email

URL of accessibility contact form

Accessibility contact name

Description of derogated content

Test environments used

e.g. 'JAWS', 'NVDA', 'VoiceOver'

e.g. 'Firefox', 'Chrome'

e.g. 'Windows', 'macOS'

e.g. 'Desktop' or 'Mobile'

platform operatingSystem assistiveTechnology browser

Organisation requesting the audit

Description of non-compliant content

Description of content not in scope

General audit notes (rich text)

Page ID (include to update existing page)

URL of the audited site

Technologies used on the site (e.g. ['HTML', 'CSS', 'JavaScript'])

Audit tools used (e.g. ['Axe', 'WAVE'])

Transverse elements (e.g. ['En-tête', 'Pied de page'])

The editUniqueId of the audit

uniqueId auditType procedureName pages auditorName auditorEmail

Update an audit (full replace)

Update criterion results for an audit. Send an array of result items.
Each item targets one criterion on one page using (pageId, topic, criterium), and REPLACES the previous evaluation of that criterion.

The topic/criterium must be a valid RGAA combination. Topics 1-13:
1. Images, 2. Cadres, 3. Couleurs, 4. Multimédia, 5. Tableaux,
6. Liens, 7. Scripts, 8. Éléments obligatoires, 9. Structuration,
10. Présentation, 11. Formulaires, 12. Navigation, 13. Consultation

Status values: COMPLIANT, NOT_COMPLIANT, NOT_APPLICABLE, NOT_TESTED

Working through a FULL audit: 106 criteria on every page, transverse elements included. Send them page by page, or topic by topic — not in one call. Between batches, call get_audit_progress to see what is left rather than re-reading every result.

Before evaluating a criterion, call get_rgaa_criterion to read its wording and its tests: it is what lets you judge rather than guess.

Comments are stored as rich text by Ara, so this server escapes < and > before sending: quote markup freely (<th>, <label for>, <video>) and it will survive as written. Do not pre-escape.

Describing a non-compliance: the details live in notCompliantItems, one entry per issue found, each with its own title, comment, userImpact (MINOR | MAJOR | BLOCKING) and quickWin. The API requires this array on EVERY item — send [] when there is nothing to report. Ara counts an audit as having blocking issues by looking at the userImpact of these entries, not of the criterion.

Array of criterion results to update

Comment when criterion is compliant

Criterion number within the topic

What you actually did beyond reading the HTML source. Required when the criterion demands it — call get_rgaa_criterion or get_audit_method to know. Declare only what you truly performed.

Comment when criterion is not applicable

The individual issues found for this criterion. Required by the API on EVERY item — send [] when the criterion is compliant, not applicable or not tested.

Description of the issue

Whether this issue is easy to fix

Short title of the issue

How much this issue impacts users

ID of the page being evaluated

Evaluation result

RGAA topic number (1-13)

The editUniqueId of the audit

Update criterion results

Update the accessibility statement (déclaration d'accessibilité) for an audit, REPLACING the current statement fields. This also PUBLISHES the statement: after the call the audit carries a statementPublicationDate and the déclaration is available at its public consultation URL — confirm with the user before calling it. Publishing the statement is separate from publish_audit, which publishes the audit report.

Auditing organisation

Accessibility contact email

Accessibility contact form URL

Accessibility contact name

The editUniqueId of the audit

Test environments

Organisation requesting the audit

URL of the audited site

Technologies used

Audit tools used

Update the accessibility statement


Fetch the lyrics of one track from LRCLIB, given the id returned by search_tracks, or an exact artist and title. Set 'format' to "synced" for karaoke-style lyrics with a timestamp on every line, "plain" for the text alone, or "both". Check 'has_synced_lyrics' in the search results first: not every track has timed lyrics. Lyrics can be long, so the text is truncated by default: check 'truncated' and call again with 'offset' set to 'next_offset' to continue reading. Instrumental tracks come back with status "instrumental" and no text, which is a valid answer, so do not retry them. Always cite 'attribution' when showing lyrics to a user.

Album name, to pick between releases.

Artist name, matched exactly by LRCLIB. Required when 'id' is absent.

Track duration, to pick between versions of differing length.

'plain' returns the text only. 'synced' returns LRC text plus a parsed list of timestamped lines. 'both' returns each of them.

LRCLIB track id, as returned by search_tracks. Preferred over the name fields.

Maximum characters of lyrics text to return in this call.

Character offset to resume from, for lyrics longer than max_chars.

Song title, matched exactly by LRCLIB. Required when 'id' is absent.

Which body the character counts and the offset describe. Timed text carries its timestamps, so it is longer than the words alone.

Parsed timestamped lines.

Raw LRC text, one timestamp per line.

Get lyrics

Look up one LRCLIB track by its id and return its metadata without the lyrics: title, artist, album, duration, and whether plain and time-synced lyrics exist. Use this to confirm you have the right release or version before calling get_lyrics, or to check whether timed lyrics exist for a track id you already hold.

Duration as m:ss, when known.

True when time-synced (LRC) lyrics are available for this track.

LRCLIB track id. Pass this to get_lyrics or get_track.

True when LRCLIB marks the track as having no vocals.

Get track metadata

Search LRCLIB for tracks by title, artist or album, and get the id needed to fetch lyrics with get_lyrics. Give either 'query' as free text, or 'track_name' and 'artist_name' separately for a narrower search. Results carry metadata only: title, artist, album, duration, and whether plain and time-synced lyrics exist. Use 'duration_seconds' and 'album_name' in the results to tell releases and re-recordings of the same song apart, and 'has_synced_lyrics' to know whether karaoke-style timed lyrics are available before fetching them. LRCLIB indexes tracks by their metadata, so it cannot search for a word appearing inside the lyrics.

Album name, to narrow a structured search.

Artist name, for a structured search.

Maximum tracks to return. LRCLIB returns up to 20 per search.

Free-text search, for example 'nino ferrer le sud'. Use this or the fields below.

Song title, for a structured search.

Tracks LRCLIB returned before applying 'limit'.

Search tracks


discover

Discover the complete i18n setup. Returns project config (locales, default locale, layers, fallback chain, glossary, translation style) plus per-layer directory listings with file counts and top-level key namespaces, and the active translation mode ("provider" when the server has an env-configured LLM provider, "agent" otherwise). Call this first to understand the project before reading or writing translations. layerGraph answers where a new key belongs: a key used by more than one app belongs in a layer those apps share, and layerGraph.shared names those layers.

Absolute path to the project root. Defaults to I18N_PROJECT_DIR, then server cwd.

Discover i18n Setup

Find translation keys defined in BOTH a shared layer and an app layer that consumes it (e.g. the same key in a monorepo root layer and in app-shop). At runtime the app layer's value shadows the shared one — collisions with divergent values are the dangerous case, because the shared value silently never shows. Compares one reference locale and reports each collision with both values and a divergent flag. Fix by deleting one side, never by moving.

When true, also groups different keys carrying the same value — e.g. common.actions.save and calendar.views.save both "Speichern". Each group says what to do about it: "reuse" (a shared layer already has it — delete the app copies and repoint call sites), "promote" (move one to a shared layer with move_translation_key), or "consolidate" (duplication inside one layer). Default: false.

Locale code to compare values in (e.g., "de", "en-US"). Defaults to the project default locale.

Shortest value worth grouping when byValue is set. Default: 4 — below it, values like "OK" repeat across unrelated namespaces legitimately.

Absolute path to write full JSON output. Returns only a compact summary to the caller — use this for large outputs to avoid flooding the conversation context. Example: "/tmp/duplicate-keys.json"

Absolute path to the Nuxt project root. Defaults to I18N_PROJECT_DIR, then server cwd. Example: "/home/user/my-app".

Find Duplicate Translation Keys Across Layers

Find keys whose value is an empty string. These exist in the locale file, so they are not reported as missing, and they render as nothing in the UI. Use this after a scaffold or an interrupted translation run to find keys that were created but never filled.

Layer name to filter by (e.g., "root", "app-admin"). If omitted, checks all layers. Call discover to discover available layers.

Locale to check (e.g., "de"). If omitted, checks every locale.

Absolute path to write full JSON output. Returns only a compact summary to the caller — use this for large outputs to avoid flooding the conversation context. Example: "/tmp/empty-translations.json"

Find Empty Translations

Find translation keys that exist in locale JSON files but are not referenced in any Vue/TS source code. Scans a specific layer or all layers. Reports keys that can potentially be removed. Also detects dynamic key patterns and uncertain matches. Scope-aware: each layer is checked only against code of the apps that consume it (summary.scanScope shows each layer's effective scope); keys referenced only from non-consuming apps are reported separately as misplacedUsages, not orphans.

Directory names to skip when scanning source files. Example: ["storybook", "__tests__", "node_modules"].

Layer name to check for orphan keys (e.g., "root", "app-admin"). If omitted, checks all layers. Call discover to see available layers.

Locale code to read translation keys from (e.g., "en", "en-US"). Defaults to the project default locale.

Absolute path to write full JSON output. Returns only a compact summary to the caller — use this for large outputs to avoid flooding the conversation context. Example: "/tmp/orphan-keys.json"

Absolute paths to directories to scan for source code usage. Overrides scope-aware scanning: all layers are checked globally against these dirs. Example: ["/home/user/my-app/apps/admin"].

Find Orphan Translation Keys

The inverse of find_orphan_keys: find keys referenced in source code but defined in NO locale file of the using app's consumed layers — the direction that ships raw keys to production. Scope-aware: each scan unit (app) is checked against the layers it consumes (summary.searchedLayersByApp); a key defined only in a layer the using app does not consume is still undefined for that app. Known limitation: extraction is line-based and static — dynamically built keys (template literals, concatenation) cannot be verified and are reported as uncertainKeys, never as hard findings.

Reference locale to resolve key definitions in (e.g., "en", "en-US"). Defaults to the project default locale.

Absolute path to write full JSON output. Returns only a compact summary to the caller — use this for large outputs to avoid flooding the conversation context. Example: "/tmp/undefined-keys.json"

Absolute paths to directories to scan for source code usage. Overrides scope-aware scanning: every layer counts as resolvable from these dirs. Example: ["/home/user/my-app/apps/admin"].

Find Used-But-Undefined Translation Keys

Find translation keys that exist in the reference locale but are missing in other locales. Scans a specific layer or all layers.

Layer name to scan (e.g., "root", "app-admin"). If omitted, scans all layers. Call discover to discover available layers.

Absolute path to write full JSON output. Returns only a compact summary to the caller — use this for large outputs to avoid flooding the conversation context. Example: "/tmp/missing-translations.json"

Locale code used as the source of truth (e.g., "en", "en-US"). Defaults to the project default locale.

Locale codes to check for missing keys (e.g., ["de", "fr", "es"]). Defaults to all locales except the reference.

Get Missing Translations

Translation coverage in one call: per-locale and per-layer counts of total, translated, missing and empty keys, plus an overall completion percentage. Use this instead of calling get_missing_translations per layer and counting keys yourself. Empty-string values count as untranslated. Locales listed in protectedLocales are reported but excluded from the overall figure, since they are maintained by hand.

Layer name to scan (e.g., "root", "app-admin"). If omitted, scans all layers.

Absolute path to write the full per-locale and per-layer breakdown. Returns only the summary to the caller.

Absolute path to the project root. Defaults to I18N_PROJECT_DIR, then server cwd.

Get Translation Status

Get translation values for given key paths from a specific locale and layer. Use "*" as locale to read from all locales.

When true and locale is "*", returns a compact summary grouped by key instead of per-locale detail. Default: false.

Dot-separated key paths to read. Example: ["common.actions.save", "auth.login.title"].

Layer name from discover (e.g., "root", "app-admin"). Call discover to discover available layers.

Locale code, locale file name, or "*" to read all locales. Examples: "en", "en-US", "en-US.json", "*".

Get Translations

List the translation key tree grouped by namespace prefix. Returns a hierarchical view of all keys with counts per namespace node. Use this to explore available keys without guessing path prefixes.

Layer name to filter by (e.g., "root", "app-admin"). If omitted or "*", scans all layers. Call discover to discover available layers.

Locale to read keys from (e.g., "en"). Defaults to the project default locale. Keys are the same across locales — only one is needed.

Absolute path to the project root. Defaults to I18N_PROJECT_DIR, then server cwd. Example: "/home/user/my-app".

List Namespaces

Move a key from one layer to another, carrying every locale that defines it — promoting an app-layer key to a shared layer once a second app needs it, or demoting a shared key that turned out to be app-specific. Call discover first: layerGraph.shared names the layers more than one app consumes. Writes nothing at all if the target layer already holds the key with a different value in any locale; if it holds the same value, that locale is deduplicated instead. Use dryRun to preview the plan.

When true, returns the plan without writing any files. Default: false.

Layer the key lives in today, from discover. Example: "app-admin".

Dot-separated key path to move. Example: "calendar.views.save".

Key path in the target layer, when the move also renames it. Example: "common.actions.save". Defaults to the same path.

Layer to move it to, from discover. Example: "root". Must differ from fromLayer — to rename within one layer, use rename_translation_key.

Move Translation Key Between Layers

Find orphan keys (not referenced in source code) and remove them from all locale files. Always does a dry run first. Scope-aware like find_orphan_keys: each layer is checked against its consuming apps (summary.scanScope), and keys referenced only from non-consuming apps are reported as misplacedUsages and never removed.

When true (default), only reports what would be removed without deleting anything. Set to false to permanently delete orphan keys.

Directory names to skip when scanning source files. Example: ["storybook", "__tests__", "node_modules"].

Layer name to clean up (e.g., "root", "app-admin"). If omitted, cleans all layers. Call discover to discover available layers.

Locale code to read translation keys from for orphan detection (e.g., "en", "en-US"). Defaults to the project default locale.

Absolute path to write full JSON output. Returns only a compact summary to the caller — use this for large outputs to avoid flooding the conversation context. Example: "/tmp/cleanup-unused.json"

Remove Orphan Keys

Remove one or more translation keys from ALL locale files in the specified layer. Use dryRun to preview changes before applying them.

When true, returns a preview of what would be removed without writing any files. Default: false.

Dot-separated key paths to remove from every locale file in the layer. Example: ["common.actions.delete", "auth.errors.expired"].

Layer name from discover (e.g., "root", "app-admin"). The key will be removed from ALL locale files in this layer.

Remove Translations

Rename/move a translation key across ALL locale files in a layer. Preserves the value in every locale. Use dryRun to preview changes before applying them.

When true, returns a preview of what would be renamed without writing any files. Default: false.

Layer name from discover (e.g., "root", "app-admin"). The key will be renamed in ALL locale files in this layer.

New dot-separated key path after renaming. Example: "common.buttons.save". Must not already exist.

Current dot-separated key path to rename. Example: "common.actions.save".

Rename Translation Key

Create empty locale files for new languages. Copies the key structure from the default locale with all values set to empty strings. Supports both JSON (Nuxt) and PHP (Laravel) formats. Does NOT modify framework config — the agent must add the locale to the framework config before calling this tool.

When true, returns what files would be created without writing them. Default: false.

Scope scaffolding to a single layer (e.g., "root", "app-admin"). If omitted, scaffolds across all layers. Call discover to discover available layers.

Locale codes to scaffold empty files for (e.g., ["sv", "ja", "pt-BR"]). If omitted, auto-detects locales defined in config that are missing locale files.

Scaffold Locale

Search translation files by key path or value. Simple case-insensitive substring match — not fuzzy or regex. Useful for finding existing translations before adding duplicates.

Layer name to search in (e.g., "root", "app-admin"), or "*" for all layers. If omitted, searches all layers. Call discover to discover available layers.

Locale code to search in (e.g., "en", "de"). If omitted, searches all locales.

Absolute path to write full JSON output. Returns only a compact summary to the caller — use this for large outputs to avoid flooding the conversation context. Example: "/tmp/search-results.json"

Substring to search for. Matched against translation keys and/or string values. Case-insensitive. Example: "save" matches key "common.actions.save" or value "Save changes".

Whether to search in translation keys, values, or both. Default: "both".

Search Translations

Translate Single Key

Add/update one source translation key and translate it into target locales. Unlike translate_missing, this can overwrite existing stale target translations. Same two modes as translate_missing: provider mode (server env-configured) translates directly; agent mode returns a fallbackContext — translate it inline and persist via write_translations.

When true, previews source/target locales without writing files or calling the translation backend.

When true, include translated values in output. Default false to keep responses compact.

Dot-separated key path to translate. Example: "bookingCreator.options.removeSubResource".

Layer name from discover to update (e.g., "root", "app-admin").

When true, overwrite existing target translations. When false, only fill missing targets. Default: true.

Absolute path to the Nuxt project root. Defaults to I18N_PROJECT_DIR, then server cwd.

Source locale ref. May be code ("en-us"), language ("en-US"), or file ("en-US.json").

Optional source value. If provided, source locale is added/updated before translating. If omitted, existing source value is read.

Target locales to translate into. Use "all" or omit for all locales except source.

Translate Key

Translate Missing Translations

Find keys missing in target locales and translate them. Two modes: in provider mode (server env-configured with I18N_PROVIDER, I18N_MODEL, and an API key) the server calls the LLM provider directly and writes the results; in agent mode (no provider configured) it returns per-locale fallbackContexts — translate those inline and persist via write_translations. Check the discover output for the active mode. Uses project config (glossary, translation prompt, locale notes, examples) if available. Translates all locales concurrently by default — pass all targetLocales at once.

Max keys per provider request (provider mode only). Default: 50. Lower values reduce per-batch risk but increase round trips.

When true, returns a compact summary (totalTranslated, totalFailed, byLocale) instead of full per-locale results. Default: false.

When true, returns which keys would be translated without calling the LLM or writing files. Default: false.

Specific dot-path keys to translate (e.g., ["auth.login.title", "common.save"]). If omitted, translates all missing keys in the layer.

Layer name from discover to translate (e.g., "root", "app-admin"). Omit to translate every locale-backed layer in one call — the recommended default for layered projects, which returns a result per layer plus an aggregated summary.

Locale code used as translation source (e.g., "en", "en-US"). Defaults to the project default locale.

Locale codes to translate into (e.g., ["de", "fr", "sv"]). Defaults to all locales except the reference.

Translate Missing

Write translation key-value pairs to a layer. Mode "upsert" adds new keys and updates existing ones (default, most common). Mode "add" only creates new keys, skipping existing ones. Mode "update" only modifies existing keys, skipping missing ones. Keys are inserted in alphabetical order. Use dryRun to preview without writing.

When true, returns a preview of what would be written without writing any files. Default: false.

Layer name (e.g., "root", "app-admin"). Discover layers via the discover tool.

Write mode. "upsert": add-or-update (never fails). "add": only new keys. "update": only existing keys. Default: "upsert".

Translation string value for this locale

Locale code or file name, e.g. "en", "en-US", "en-US.json"

Map of dot-path keys to locale-value pairs. IMPORTANT: values must be locale maps, NOT plain strings. Locale refs may be code ("en-us"), language ("en-US"), or file ("en-US.json"). Wrong: { "auth.failed": "Login failed" }. Correct: { "auth.failed": { "en-US": "Login failed", "de-DE": "Anmeldung fehlgeschlagen" } }

Dot-separated key path, e.g. "auth.login.title"

Write Translations


Account Usage

Check the user's OpenEphemeris account usage and remaining credits. Returns their plan tier, billing period, credits used / included / remaining, percent of quota used, total API calls, and subscription status with renewal date.

✅  USE THIS TOOL FOR: 'How many credits do I have left?', 'What's my usage this month?', 'Am I close to my limit?', 'What plan am I on?', 'How do I upgrade or top up?'

CREDIT COST: Free (0 credits).

EXAMPLE: Check current usage:
  (call with no arguments)

EXAMPLE: Check a past month:
  month='2026-06'

Billing month to query in YYYY-MM format (e.g. '2026-06'). Defaults to the current month.

Astrocartography Location Hits

Find all Astrocartography lines (power lines + aspect lines) passing near a specific location. Returns features sorted by distance, making it easy to interpret planetary influences at a place.

✅  USE THIS TOOL FOR: 'Is [city] good for me?', 'What planets affect me in Tokyo?', 'What ACG lines run through Paris for my chart?', 'Which cities are under my Jupiter line?'
❌  NOT FOR: Full global map geometry → use acg_power_lines for that instead.

CREDIT COST: 10 credits per call.

EXAMPLE: All ACG lines within 3° of Paris for a chart born 1990-04-15 in Chicago:
  birth_datetime='1990-04-15T14:30:00', timezone='America/Chicago',
  birth_latitude=41.8781, birth_longitude=-87.6298,
  query_latitude=48.8566, query_longitude=2.3522, radius_deg=3

ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. Date-only resolves to 12:00 UTC. Full rule: server `instructions`. An unstated zone moves every ACG line by ~15° of longitude per hour.

Birth latitude in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory.

Birth longitude in decimal degrees.

List of celestial bodies for line calculation. E.g. ['Sun', 'Moon', 'Venus', 'Mars', 'Jupiter', 'Saturn']. Aliases: 'NorthNode'/'Node'/'Rahu' → MeanNode, 'SouthNode'/'Ketu' → SouthNode. Omit to use all classical planets.

Include aspect lines in results (default true).

Latitude of the location to check for nearby lines.

Longitude of the location to check for nearby lines.

Search radius in degrees (default 2°, max 90°).

IANA timezone (e.g. `America/Chicago`); required when the datetime is naive, ignored otherwise.

Astrocartography Lines

Calculate Astrocartography power lines (MC, IC, AC/ASC, DC/DSC) for a natal chart. Returns GeoJSON LineStrings tracing each planetary angle line around the globe. These are the latitudinal lines where a planet was rising (AC), setting (DC), culminating (MC), or anti-culminating (IC) at birth.

❌  NOT FOR: 'Is [city] good for me?' or 'What planets affect me in Tokyo?' → For a specific city/location analysis, use acg_hits instead (faster and more relevant).
✅  USE FOR: Getting the full global GeoJSON line geometry for map rendering or bulk geographic analysis.

CREDIT COST: 10 credits per call.

EXAMPLE: Saturn and Jupiter power lines for a chart born 1990-04-15 at 2:30 PM in Chicago:
  birth_datetime='1990-04-15T14:30:00', timezone='America/Chicago',
  birth_latitude=41.8781, birth_longitude=-87.6298, bodies=['Saturn', 'Jupiter']

Birth longitude in decimal degrees.

Filter lines near this latitude (optional, for hits mode).

Filter lines near this longitude (optional, for hits mode).

Search radius in degrees for hits filtering. Default 2°.

Connect Account

Start the device authorization flow to connect this MCP server to your OpenEphemeris account (free tier, no credit card needed). Returns a verification URL and code for the user to enter in their browser. The MCP server will then automatically receive credentials and all API calls will be linked to the user's account (tier, credits, rate limits). Only needed if no OPENEPHEMERIS_API_KEY env var is set and no cached credentials exist.

Disconnect Account

Disconnect this MCP server from your OpenEphemeris account by clearing cached credentials. Does NOT revoke the API key if one is set via environment variable — only clears device-auth cached credentials.

Auth Status

Check the current authentication status of this MCP server. Shows whether the server is authenticated, which account it's linked to, the authentication method (API key, JWT, device auth), and token expiry.

BaZi Annual Pillar

Look up the sexagenary pillar for any Gregorian year (1–9999). Returns the Heavenly Stem, Earthly Branch, Chinese characters, zodiac animal, element, polarity, and NaYin (纳音) poetic resonance image.

NaYin maps each pair in the 60-cycle sexagenary sequence to one of 30 elemental images (e.g. '海中金 Metal in the Sea', '炉中火 Fire in the Furnace'). It is traditionally applied to the Year and Day pillars to reveal deeper elemental character.

Use this to:
  • Identify the energetic quality of any given year
  • Determine a person's birth year pillar for compatibility context
  • Find the NaYin element for year or day interpretations

CREDIT COST: 3 credits per call.

EXAMPLE: Year pillar for 2025:
  year=2025

Gregorian year (1–9999). e.g. 2025.

List Allowed API Operations

List all API operations (method + path) that this MCP instance is authorized to call. Returns endpoint entries grouped by method, plus the active deny rules. Use this to discover what's available before calling dev_read_api, or to verify an endpoint path. Typed shortcut tools (ephemeris_natal_chart, ephemeris_transits, etc.) cover the most common operations — check those first before reaching for the generic proxies.

API Read

Read from any allowlisted Open Ephemeris API endpoint via HTTP GET. This is the read-only power-user escape hatch — use the typed tools (ephemeris_natal_chart, ephemeris_transits, etc.) first for common operations. Endpoints that compute via POST (natal-chart, synastry, etc.) are covered by the typed tools; the generic POST proxy is only exposed on the full tool surface (`?profile=full`).

Target API: Open Ephemeris REST API (https://api.openephemeris.com). Call dev_list_allowed to see all currently available endpoint paths.

AUTH: Set OPENEPHEMERIS_API_KEY in your environment. See openephemeris.com/dashboard for active plan limits.

CREDIT COSTS:
  • Standard chart math (natal, progressed, bazi, vedic, iching): 1 credit
  • Human Design: 2 credits
  • Visualization rendering (chart-wheel, bi-wheel, charts/*): 2 credits
  • Comparative math (synastry, composite, overlay): 3 credits
  • Predictive ops (transits/search, returns): 5 credits
  • Predictive transit-chart: 1 credit
  • ACG / astrocartography: 10 credits (acg/hits: 15 credits)
  • Calendar endpoints: 10 credits
  • Catalog / metadata / health endpoints: 0 credits
  • Compute surcharge: requests > 30s add 1 credit per 30s (predictive, acg, calendar, electional)
  • format=llm (token-optimized output): available on all tiers

BINARY RESPONSES:
  • Binary/image endpoints return {content_type, content_length, encoding, data_base64}
    so callers can decode bytes deterministically.

ECLIPSE NOTE: Eclipse endpoints accept format=llm via the query param like other endpoints.

format=llm NOTE: Add query: {format: 'llm'} to natal/synastry/composite/HD endpoints for compact columnar output optimized for LLM token budgets (availability depends on your current plan).

COMMON CALLS:
  GET  /ephemeris/moon/phase             — Current/queried moon phase
  GET  /ephemeris/moon/void-of-course    — Next void-of-course period
  GET  /ephemeris/agro/daily             — Biodynamic farming day quality
  GET  /ephemeris/agro/calendar          — Multi-day biodynamic calendar
  GET  /ephemeris/agro/void-of-course    — Biodynamic VoC periods
  GET  /eclipse/next-visible             — Next eclipse visible from a location (query: lat, lon, type=solar|lunar)
  GET  /eclipse/solar/global             — Next global solar eclipse (query: date=YYYY-MM-DD)
  GET  /eclipse/solar/local              — Local solar eclipse (query: lat, lon)
  GET  /tidal/forcing                    — Gravitational tidal forcing index
  GET  /calendar/astrology/moon-phases   — Moon phase calendar for a date range
  GET  /location/autocomplete            — Geocode a place name (query: query=City Name)
  GET  /chinese/zodiac                   — Chinese zodiac year element/animal
  GET  /catalogs/bodies                  — List all supported celestial bodies

JSON request body (optional)

Convenience: if provided, set query.format (optional). 'llm' is canonical; 'llm_v2' is accepted as a legacy alias.

HTTP method (always GET)

Legacy convenience (deprecated): if provided, set query.output_mode and also map to query.preset/query.format when possible.

Absolute API path (e.g., /ephemeris/natal-chart)

Convenience: if provided, set query.preset (optional).

Query params (optional)

Moment Quality Analysis

Analyze the astrological quality of a specific moment: planet positions, aspects, void of course status, lunar phase, day ruler, sect, and an overall electional score (0-100). Perfect for evaluating whether 'right now' or a specific date/time is good for action.

CREDIT COST: 5 credits per call.

EXAMPLE: Analyze March 21, 2026 at noon in New York:
  date='2026-03-21T12:00:00Z', latitude=40.7128, longitude=-74.0060

ISO 8601 datetime to analyze, with a zone (e.g., '2026-03-21T12:00:00Z' or '2026-03-21T08:00:00-04:00'). Defaults to now.

Output format.

Latitude of location in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory. Optional, but pass both whenever the place is known — without them sect falls back to diurnal and a night moment is scored with the DAY triplicity rulers.

Longitude of location in decimal degrees (positive = East). Needed alongside latitude — day/night is a local fact that neither coordinate settles alone.

Retrograde Station Tracker

Find all upcoming retrograde and direct stations for planets in a date range. Returns exact station times, longitudes, and signs.

USE THIS TOOL FOR: 'When does Mercury go retrograde?', 'Is Venus retrograde this year?', 'What planets station this month?', 'When does Mars go direct?'

❌  NOT FOR: 'Is Mercury retrograde right now?' — that is the state at a single instant, so use ephemeris_retrograde_status (1 credit for one planet, vs 5 here).

All required fields have smart defaults (searches the next 90 days from today).

CREDIT COST: 5 credits per call.

EXAMPLE: Mercury and Venus stations in the next 3 months (all defaults):
  (no args required, will auto-scan next 90 days for all inner planets)

EXAMPLE: Outer planet stations in 2026:
  start_date='2026-01-01', end_date='2026-12-31', planets='jupiter,saturn,uranus,neptune,pluto'

End date (ISO 8601). Defaults to +90 days.

Output format.

Comma-separated planet names to track. E.g. 'mercury,venus,mars' or 'jupiter,saturn,uranus,neptune,pluto'. Defaults to Mercury through Saturn (inner + classical planets).

Start date (ISO 8601). Defaults to today.

Angles & Points

Calculate chart angles and sensitive points (ASC, MC, DSC, IC, Vertex, Equatorial Ascendant/Descendant) for a given date/time and location. The equatorial ascendant is also returned under the key `east_point` — a synonym for the same point, not a separate one.

CREDIT COST: 1 credit per call.

ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. Date-only resolves to 12:00 UTC. Full rule: server `instructions`.

Observer latitude.

Observer longitude.

IANA timezone (e.g. `America/Chicago`); required when the datetime is naive, ignored otherwise.

Aspect Check

Check the aspect between two ecliptic longitudes. Returns the angular separation and any aspects within orb (conjunction, sextile, square, trine, opposition, etc.).

CREDIT COST: 1 credit per call.

EXAMPLE: Check aspect between 15° Aries and 75° Gemini:
  longitude_1=15, longitude_2=75

First ecliptic longitude (0-360).

Second ecliptic longitude (0-360).

Maximum orb in degrees. Default 8°.

Electional Timing Window

Find optimal planetary timing windows (electional astrology). Scans a date range to find the best times for an event based on essential dignity, aspect quality, sect, and void-of-course moon penalties. Evaluates every hour and clusters the best continuous windows.

CREDIT COST: 5 credits per call (heavy calculation).

EXAMPLE: Find the best time to launch a business in early March 2026.
  start_date='2026-03-01', end_date='2026-03-10', latitude=40.7128, longitude=-74.0060,
  avoid_voc=true, lunar_phase='waxing'

Comma-separated list of planets to avoid when retrograde (e.g., 'mercury,venus').

If true, strictly ignores any moments where the Moon is Void of Course.

End of the search window. ISO 8601 date or zoned datetime; a naive clock time is rejected. Date-only resolves to 12:00 UTC.

Output format. 'llm' = compact token-efficient output (available on all tiers).

Latitude of location in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory.

Longitude of location in decimal degrees (positive = East).

Filter windows by lunar phase. Defaults to 'any'.

Maximum number of top windows to return (default 5).

Start of the search window, e.g. '2026-03-01'. ISO 8601 date or zoned datetime; a naive clock time is rejected. Date-only resolves to 12:00 UTC.

House Cusps

Calculate house cusps and angles (ASC, MC, DSC, IC) for a given date, time, and location using one or more house systems.

House system codes: P=Placidus, K=Koch, O=Porphyry, R=Regiomontanus, C=Campanus, E=Equal, W=Whole Sign.

CREDIT COST: 1 credit per call.

EXAMPLE: Placidus houses for London at 2026-03-20 noon UTC:
  datetime='2026-03-20T12:00:00Z', latitude=51.5074, longitude=-0.1278, house_systems=['P']

List of house system codes. E.g. ['P', 'W']. Defaults to ['P'] (Placidus).

Observer latitude in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory.

Observer longitude in decimal degrees.

Moon Phase

Get the Moon's current phase angle, illumination, sign and void-of-course status AT a specific point in time. Returns phase name (New, Waxing Crescent, etc.), illumination %, the zodiac sign and degree the Moon occupies, and next void-of-course period.

⚠  THIS TOOL ANSWERS: 'What phase is the moon in right now (or at a given datetime)?' and 'What sign is the moon in?'
❌  THIS TOOL DOES NOT ANSWER: 'When is the next new moon / full moon?'
→   For upcoming phase DATES use ephemeris_next_lunar_phase instead.

For a user-facing interactive moon-phase dial, use explore_moon_phase instead.

CREDIT COST: 2 credits — phase and void-of-course are metered separately. For phase alone at 1 credit, use dev_read_api path='/ephemeris/moon/phase'.

If no datetime is provided, returns the current (live) moon phase.

ISO 8601 datetime to query, stating its zone ('2026-03-20T12:00:00Z' or '2026-03-20T08:00:00-04:00'), or a local time together with `timezone`. If omitted, returns the current live moon phase (UTC now).

Observer latitude (optional, used for local void-of-course calculations).

Observer longitude (optional, used for local void-of-course calculations).

IANA timezone (e.g. `America/Chicago`); required when the datetime is naive, ignored otherwise.

Natal Chart

Calculate a full natal (birth) chart for a person. Returns planetary positions, house cusps, aspects, and chart patterns. Use format='llm' for a compact, token-efficient output ideal for interpretation (available on all tiers). The result includes all major planets, Chiron and major asteroids like Ceres, angles (ASC/MC/DSC/IC), essential dignities, retrograde status, house system data, and major aspect grid. Asteroids are automatically included. Returns raw JSON. For a user-facing visual chart, use explore_natal_chart instead.

CREDIT COST: 1 credit per call.

EXAMPLE: born 15 April 1990 at 2:30 PM local time in Chicago — pass the local time and name the zone:
  datetime='1990-04-15T14:30:00', timezone='America/Chicago', latitude=41.8781, longitude=-87.6298
Equivalently, put the zone on the datetime: datetime='1990-04-15T14:30:00-05:00' (or the UTC instant '1990-04-15T19:30:00Z').

Optional whole-chart analytics, off by default: element_balance (fire/earth/air/water plus modality counts over the classical ten, unweighted), hemisphere_emphasis (above/below and east/west from the angles), aspect_patterns (aspect matrix + detected patterns), harmonics. No extra credits. Absent from format='llm'.

Sidereal system. Default lahiri. Only read when zodiac_type is `sidereal`.

lahiri fagan_bradley krishnamurti raman yukteshwar

ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. Date-only resolves to 12:00 UTC. Full rule: server `instructions`.

Add each body's declination and out-of-bounds flag, plus parallel/contraparallel aspects (1.5° orb).

Output format. 'llm' returns a compact array-based projection optimized for LLM token efficiency (available on all tiers). 'json' returns full verbose JSON.

House system to use. Defaults to 'placidus' if omitted.

placidus whole_sign equal koch campanus regiomontanus porphyry

Include Hermetic Lots / Arabic Parts in the natal response (routed as `options.include_hermetic_lots: true`). For a standalone lots-only payload without a full natal chart, use `/ephemeris/hermetic-lots` instead.

Add fixed-star conjunctions (Regulus, Algol, Spica and the catalog) against the chart's bodies and angles. Honoured by the endpoint since 4.14.0; same zodiac frame as the chart.

Add quincunx, semisextile, semisquare, sesquiquadrate, quintile and biquintile to the aspect grid. Off by default; minors use their own orbs, so this widens the grid without changing any major aspect.

When true, renders the natal chart wheel as an SVG and embeds it directly in the response. The chart image will display in the conversation alongside the data. Costs 2 additional credits on top of the base call cost.

Geographic latitude of birth location in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory.

Geographic longitude of birth location in decimal degrees (positive = East).

Classify combustion, cazimi and under-beams for Moon–Saturn relative to the Sun.

Optional rendering preferences (only used when include_visual=true).

Canvas size in pixels, 200–4000. Default: 800.

Color theme. Default: light.

Zodiac frame. Default tropical. `sidereal` subtracts the ayanamsa (~24°) from every longitude, so signs, dignities and element balance all move; aspects and house numbers do not. The response names the frame it used.

Eclipse Finder

Find the next solar or lunar eclipse. Returns the eclipse type, date/time of maximum, magnitude, and duration of totality (if any).

📍 LOCATION OPTIONAL:
  • WITH latitude+longitude → returns local contact times and visibility for that specific location.
  • WITHOUT latitude+longitude → returns the next global eclipse of that type (no location needed).

USE THIS TOOL FOR: 'When is the next solar eclipse?', 'When is the next total lunar eclipse?', 'Will there be an eclipse visible from Tokyo?'

CREDIT COST: 1 credit per call.

EXAMPLE: Next solar eclipse globally (no location needed):
  eclipse_type='solar'

EXAMPLE: Next solar eclipse visible from New York:
  eclipse_type='solar', latitude=40.7128, longitude=-74.006

EXAMPLE: Next lunar eclipse from London:
  eclipse_type='lunar', latitude=51.5074, longitude=-0.1278

ISO 8601 date to search after (e.g. '2026-01-01'). Defaults to today if omitted.

Eclipse type to search for. Use 'any' for whichever comes first (solar or lunar).

Observer latitude in decimal degrees (optional). When provided with longitude, returns local contact times and visibility.

Observer longitude in decimal degrees (optional, pair with latitude).

Next Lunar Phase

Find the next occurrence of a specific Moon phase after a given date. Returns the exact UTC datetime of each occurrence.

✅  USE THIS TOOL FOR: 'When is the next new moon?', 'When is the next full moon?', 'What date is the next quarter moon?', or any question about UPCOMING phase dates.
❌  NOT FOR: 'What phase is the moon in right now?' or 'What sign is the moon in?'
→   For the phase, sign and degree AT a moment, use ephemeris_moon_phase.

CREDIT COST: 1-2 credits per occurrence returned — each occurrence takes one calendar search, plus a second search when the first window misses. So count=3 costs 3-6 credits.

EXAMPLE: Find the next new moon:
  phase='new_moon'

EXAMPLE: Find the next full moon after a specific date:
  phase='full_moon', after_date='2026-06-01'

EXAMPLE: Find the next 3 full moons:
  phase='full_moon', count=3

ISO 8601 date to search from (e.g. '2026-06-01'). Defaults to today (UTC) if omitted.

Number of upcoming occurrences to return (1-12). Default 1.

The lunar phase to find. 'new_moon' = conjunction (0° Sun-Moon, start of cycle). 'full_moon' = opposition (180°). 'first_quarter' = 90° waxing. 'last_quarter' = 270° waning.

Planet Position

Get the precise ecliptic longitude, latitude, distance, speed, and retrograde status for a single planet/body at a given date and time. Planet IDs: 0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto, 10=North Node (Mean), 11=North Node (True), 12=Lilith (Mean), 15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta.

SOUTH NODE: there is no South Node id. The South Node is always exactly opposite the North Node — request id 10 or 11 and add 180° (mod 360).

CREDIT COST: 1 credit per call.

EXAMPLE: Where is Mars on 2026-03-20 at noon UTC?
  planet_id=4, datetime='2026-03-20T12:00:00Z'

ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. Date-only resolves to 12:00 UTC. Full rule: server `instructions`.

Observer latitude for topocentric position (optional). Omit for geocentric.

Observer longitude for topocentric position (optional). Omit for geocentric.

Planet/body ID (0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto, 10=North Node (Mean), 11=North Node (True), 12=Lilith (Mean), 15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta). There is no South Node id — take the North Node and add 180°.

IANA timezone (e.g. `America/Chicago`); required when the datetime is naive, ignored otherwise.

Progressed Chart

Calculate a Secondary Progressed (or Solar Arc / Tertiary) chart. Advances the natal chart symbolically — 1 day = 1 year (secondary), or using solar arc motion. Returns progressed planet positions, house cusps, aspects, and retrograde status.

CREDIT COST: 1 credit per call.

EXAMPLE: Secondary progressions for someone born 1985-06-21 at 2:00 PM in London, progressed to 2026-01-01:
  birth_datetime='1985-06-21T14:00:00', timezone='Europe/London',
  birth_latitude=51.5, birth_longitude=-0.12, target_datetime='2026-01-01', method='secondary'

Birth latitude in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory.

Birth longitude in decimal degrees.

Whether to include aspect grid in the response. Default false.

When true, renders the progressed chart wheel as an SVG and embeds it in the response. The chart image will display in the conversation alongside the data. Costs 2 additional credits on top of the base call cost.

Progression method. Defaults to 'secondary' (1 day = 1 year).

Optional label for the subject, echoed back in both natal_subject and progressed_subject. Defaults to a generic label if omitted.

Date to progress the chart to. ISO 8601 date or zoned datetime; a naive clock time is rejected. Date-only resolves to 12:00 UTC.

Optional rendering preferences (only used when include_visual=true).

Canvas size in pixels, 200–4000. Default: 800.

Color theme. Default: light.

Relocation Chart

Calculate a relocation chart — the same natal planetary positions re-cast for a different geographic location. Used to understand how living in a different city shifts house placements and angles, without changing the planetary longitudes in the chart.

CREDIT COST: 1 credit per call.

EXAMPLE: How does moving from Chicago to London change someone's chart?
  natal_datetime='1990-04-15T14:30:00', timezone='America/Chicago',
  natal_latitude=41.8781, natal_longitude=-87.6298,
  relocation_latitude=51.5074, relocation_longitude=-0.1278

Output format. 'llm' = compact token-efficient output (available on all tiers).

House system to use. Defaults to 'placidus'.

ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. Date-only resolves to 12:00 UTC. Full rule: server `instructions`.

Latitude of birth location in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory.

Longitude of birth location in decimal degrees.

Latitude of the relocation city in decimal degrees (positive = North).

Longitude of the relocation city in decimal degrees (positive = East).

IANA timezone (e.g. `America/Chicago`); required when the datetime is naive, ignored otherwise.

Retrograde Status

Get retrograde/direct status and speed for ONE planet — or, if you ask for it, all ten — at a given date/time. Returns is_retrograde flag, longitude speed, and station proximity.

✅  Answers 'is X retrograde?' at ONE instant. Pass planet_id for the named planet; 'is Mercury retrograde?' is planet_id=2, not a whole-sky sweep. For WHEN a planet turns retrograde or direct, or whether it stations anywhere in a date range, use electional_station_tracker.

CREDIT COST: 1 credit for a single planet (pass planet_id). Omitting planet_id runs the all-planets sweep and costs 10 credits — the backend bills one credit per body and this fans out to 10. Only omit it when the question really is about every planet.

Single planet ID (0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto). Pass this whenever the question names a planet — 1 credit. Omit only to sweep all ten — 10 credits.

Solar Return

Calculate the exact Solar Return date/time — when the Sun returns to its natal ecliptic longitude (happens once per year near the birthday). Returns the Solar Return chart for the year ahead.

CREDIT COST: 5 credits per call.

TARGET DATE: Provide target_datetime near the desired birthday year. If omitted, defaults to the current year's solar return.

EXAMPLE: Solar return for someone born 1985-06-21 (current year):
  birth_datetime='1985-06-21T14:00:00Z'

EXAMPLE: Solar return for 2027 specifically:
  birth_datetime='1985-06-21T14:00:00Z', target_datetime='2027-01-01T00:00:00Z'

Birth latitude in decimal degrees (optional, for location context).

Birth longitude in decimal degrees (optional, for location context).

When true, renders the solar return chart wheel as an SVG and embeds it in the response. The chart image will display in the conversation alongside the data. Costs 2 additional credits on top of the base call cost.

Location latitude for the return chart (optional, if different from birth location).

Location longitude for the return chart (optional).

Date/time near which to find the Solar Return (ISO 8601 with offset or Z). Defaults to approximately 1 year from now if omitted.

Optional rendering preferences (only used when include_visual=true).

Canvas size in pixels, 200–4000. Default: 800.

Color theme. Default: light.

Synastry Chart

Calculate a synastry chart comparing two people's natal charts. Returns inter-aspects (planetary connections between the two charts), composite points, and relationship indicators. Use this for compatibility analysis, relationship timing, or partnership insights.

CREDIT COST: 3 credits per call.

EXAMPLE: Compare two people's charts (local birth times, each with its zone):
  person_a_datetime='1990-04-15T14:30:00', person_a_timezone='America/Chicago',
  person_a_latitude=41.8781, person_a_longitude=-87.6298,
  person_b_datetime='1988-09-22T08:15:00', person_b_timezone='America/Los_Angeles',
  person_b_latitude=34.0522, person_b_longitude=-118.2437

Output format. 'llm' is compact and token-efficient (available on all tiers).

House system for both charts. Defaults to 'placidus'.

When true, renders a bi-wheel SVG comparing both charts and embeds it in the response. The chart image will display in the conversation alongside the data. Costs 2 additional credits on top of the base call cost.

ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. Date-only resolves to 12:00 UTC. Full rule: server `instructions`.

Person A birth latitude. Resolve from a place name with location_search; never recall coordinates from memory.

Person A birth longitude.

IANA timezone for Person A's birth location (e.g. `America/Chicago`); required when the datetime is naive.

Person B birth latitude.

Person B birth longitude.

IANA timezone for Person B's birth location (e.g. `America/Los_Angeles`); required when the datetime is naive.

Color theme. Default: light.

Transit Search

Search for astrological transit events affecting a natal chart over a date range. Returns exact transit moments — when transiting planets form specified aspects to natal planet positions.

EFFICIENCY TIP: Always specify both transiting_planets and natal_points to keep compute fast. Omitting both sends all outer planets against all core natal positions — a much heavier computation.

ASPECT ANGLES: Use aspect_angle to search for specific aspects:
  0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine.
  Example: Saturn Return → transiting_planets=['saturn'], natal_points=['saturn'], aspect_angle=0
  Example: Uranus Opposition → transiting_planets=['uranus'], natal_points=['uranus'], aspect_angle=180
  Example: Outer planets to natal Sun/Moon → transiting_planets=['saturn','uranus','neptune','pluto'], natal_points=['sun','moon']

DEFAULT natal_points (when omitted): sun, moon, mercury, venus, mars, jupiter, saturn.
SEARCH RANGE LIMITS: Explorer/PayG tier → 1 year max; Pro → 5 years; Startup → 10 years.
CREDIT COST: 5 credits per call.

Aspect angle in degrees to apply to each natal longitude. 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine. The effective search target becomes (natal_longitude + aspect_angle) mod 360.

End of the transit search window. ISO 8601 date or zoned datetime; a naive clock time is rejected. Date-only resolves to 12:00 UTC.

Latitude of birth location in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory.

Longitude of birth location in decimal degrees.

Natal point IDs whose exact longitudes should be targeted. E.g. ['sun', 'moon', 'asc', 'mc', 'saturn', 'chiron']. Omit for all core points.

IANA timezone for the natal birth location (e.g. `America/Chicago`); required when the datetime is naive.

Start of the transit search window. ISO 8601 date or zoned datetime; a naive clock time is rejected. Date-only resolves to 12:00 UTC.

List of transiting planet IDs to search. E.g. ['saturn', 'jupiter', 'uranus', 'pluto', 'chiron']. Omit to search all outer planets.

Interactive BaZi Four Pillars Explorer

Generate an interactive BaZi (四柱命盘 Four Pillars of Destiny) chart with clickable pillars.

Returns an embedded visual Four Pillars explorer showing the Year, Month, Day, and Hour pillars — each with its Heavenly Stem (天干) and Earthly Branch (地支), Ten God label, and element color — plus the Day Master identity and a Wu Xing (五行) element balance bar. Click any pillar for an instant interpretation of what it reveals about that life domain (Year = ancestry/early life, Month = parents/career, Day = self/spouse, Hour = children/later life).

CREDIT COST: 3 credits per call (1 base + 2 visual render).

Use this for a rich, interactive BaZi experience in MCP Apps-capable hosts (Claude Desktop). Falls back to a text summary in other hosts, so it is also the right call without a renderer. Deeper derivations (Ten Gods, element balance, luck pillars) and a plain non-visual pillars lookup have dedicated tools on the full surface (`?profile=full`).

Alternative to year/month/day: ISO 8601 datetime read as LOCAL wall-clock time at the birth place — BaZi pillars are local by definition, so a zone-less value is correct here and is NOT converted to UTC. If it carries a 'Z' or offset, also pass timezone.

Birth day of month (1–31).

Day-pillar cutover convention. Default zi_hour.

Birth hour (0–23). Optional, defaults to 12 (noon). Chinese shí hours are 2-hour blocks — precision within a 2-hour window is sufficient.

Birth latitude, decimal degrees (north+).

Birth longitude, decimal degrees (east+).

Birth minute (0–59). Optional, defaults to 0. Only matters under true_solar_time or near a boundary.

Birth month (1–12).

IANA timezone name for the birth place, e.g. 'Asia/Shanghai'. Required to convert a zoned datetime back to local clock; also frames the year/month solar-term boundary.

Apply true solar time correction (needs latitude+longitude).

Gregorian birth year, e.g. 1987.

Year-pillar cutover convention. Default lichun.

Interactive Bi-Wheel Explorer

Generate an interactive bi-wheel chart comparing two astrological chart positions.

CREDIT COST: 2 credits per call for most modes (1 per wheel computed); solar_return/lunar_return modes cost 6 (5 for the return + 1 for the natal wheel).

The inner wheel is always Person 1's natal chart. The outer ring depends on mode:
• synastry     — Person 2's natal chart (needs Person 2's own birthplace).
• transit      — Transiting planets for a given date.
• progressed   — Secondary progressed positions (person2_datetime = target date).
• solar_return — Nearest solar return chart (person2_datetime = year to return for).
• lunar_return — Nearest lunar return chart (person2_datetime = target month).
• solar_arc    — Solar arc directed positions (person2_datetime = target date).
Cross-aspects are drawn as coloured dashed lines; click any planet, aspect line, or house cusp for interpretation. Prefer this whenever the user should SEE the comparison — it renders interactively in MCP Apps hosts and falls back to static SVG elsewhere. For raw synastry data without a visual, use ephemeris_synastry.

Person 1 / Natal location. Prefer a plain place name like 'New York, NY' — resolved via the same lookup `location_search` uses; ambiguous names throw with a disambiguation hint. Supplied person1_latitude/person1_longitude win.

Chart comparison mode. Defaults to 'synastry'.

Birth datetime for Person 1 / Natal chart. ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. Date-only resolves to 12:00 UTC. Full rule: server `instructions`.

Birth latitude for Person 1 (decimal degrees, positive = North). Optional if `location` is a place name — the resolver fills it in. Never recall coordinates from memory.

Birth longitude for Person 1 (decimal degrees, positive = East). Optional if `location` is a place name.

Display name for Person 1 / Natal chart (e.g. 'Alice'). Used in the badge and summary.

IANA timezone for Person 1's birth location (e.g. `America/New_York`); required when the datetime is naive.

Datetime for the outer wheel. Meaning depends on mode: synastry = Person 2 birth datetime; transit/progressed/solar_arc = target date; solar_return/lunar_return = any date within the target year/month. ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. Date-only resolves to 12:00 UTC. Full rule: server `instructions`.

Birth latitude for Person 2. REQUIRED in synastry unless `person2_location` is given — never inferred from Person 1. Other modes default to Person 1's coords.

Person 2 / outer-chart place name, resolved like `location`. person2_latitude/person2_longitude win.

Birth longitude for Person 2. REQUIRED in synastry unless `person2_location` is given. Other modes default to Person 1's coords.

Display name for Person 2 (synastry mode). Used in the badge and summary.

IANA timezone for Person 2 / the outer chart (e.g. `America/Chicago`); required when the datetime is naive.

Interactive Human Design Bodygraph Explorer

Generate an interactive Human Design Bodygraph with clickable centers, gates, and channels.

CREDIT COST: 4 credits where the bodygraph renders (2 for the chart + 2 for the visual), 2 in text-only hosts that skip the render. For chart data alone at 2 credits — including the activations, design, personality, strategy and variables this tool does not return — use human_design_chart.

Returns an embedded visual bodygraph explorer that lets you click any center or gate for instant Human Design interpretation. Shows defined/undefined centers, active gates, channels, Type, Profile, Authority, and Incarnation Cross. The chart is calculated using NASA JPL DE440 ephemerides for both Personality and Design positions. Use this instead of human_design_chart for a richer, interactive HD experience in MCP Apps-capable hosts (Claude Desktop). Falls back to a text summary in other hosts. Human Design was originated by Ra Uru Hu; OpenEphemeris is an independent calculation service, not affiliated with Jovian Archive.

ISO 8601 birth datetime in UTC, e.g. '1990-04-15T19:30:00Z'. Human Design is time-sensitive — accuracy to the minute matters. Include 'Z' or a timezone offset.

Birth latitude in decimal degrees (positive = North). Optional if `location` is a place name — the resolver fills it in. Never recall coordinates from memory; either supply a place name or resolve with location_search first.

Birth location. Prefer a plain place name like 'New York, NY' — the server resolves it via the same lookup `location_search` uses (unambiguous names → coords + timezone; ambiguous names throw with a disambiguation hint). If neither location nor lat/lon is supplied the call is rejected — no more silent 0°N 0°E charts.

Birth longitude in decimal degrees (positive = East). Optional if `location` is a place name.

IANA timezone name for the birth location (e.g. 'America/New_York'). Highly recommended for accuracy if providing local birth time without a UTC offset. Enables correct UTC conversion for precise Personality and Design positions.

Human Design Connection (Synastry)

Compare two people's Human Design charts and classify every connected channel by HD connection theory.

CREDIT COST: 3 credits per call.

Classifications: electromagnetic (attraction), companionship (sameness), dominance (one defines), and compromise (friction). Returns an interactive two-person overlay bodygraph in MCP Apps-capable hosts, with a text summary fallback elsewhere. Premium (Pro tier). NASA JPL DE440 ephemerides. Human Design was originated by Ra Uru Hu; OpenEphemeris is an independent calculation service, not affiliated with Jovian Archive.

Overlay composition. 'graph' (default) is the classic bodygraph rectangle with connected channels classified by connection type; 'mandala' nests the same overlay inside the concentric ring set the natal chart uses. Set by the in-iframe layout toggle, never by the model.

First person's birth data.

Birth datetime, ISO 8601 (Z/offset, or local with timezone).

Birth latitude, decimal degrees (+N). Optional if `location` is set.

Birth location, e.g. 'New York, NY' — resolved like location_search (ambiguous names throw). Omitting both this and lat/lon rejects the call rather than defaulting to 0°N 0°E.

Birth longitude, decimal degrees (+E). Optional if `location` is set.

IANA timezone (e.g. 'America/New_York').

Second person's birth data.

Visual theme for the overlay bodygraph. Set automatically by the embedded app to match the host; defaults to dark. You normally never need to pass this.

Human Design Transit Overlay

Overlay the current (or a chosen) planetary transit on a person's natal Human Design bodygraph.

CREDIT COST: 3 credits per call.

Highlights the channels a transit temporarily COMPLETES with the natal chart and any centers it newly defines — the core of a Human Design transit reading. Returns an interactive overlay bodygraph in MCP Apps-capable hosts (Claude Desktop), with a text summary fallback elsewhere. Premium (Pro tier). Calculated with NASA JPL DE440 ephemerides. Human Design was originated by Ra Uru Hu; OpenEphemeris is an independent calculation service, not affiliated with Jovian Archive.

Natal birth datetime, ISO 8601 (e.g. '1990-04-15T19:30:00Z'). Include 'Z' or an offset, or supply timezone for local time. HD is time-sensitive to the minute.

Natal birth latitude in decimal degrees (positive = North). Optional if `location` is a place name — the resolver fills it in.

Overlay composition. 'graph' (default) is the classic bodygraph rectangle with the transit's activated channels highlighted; 'mandala' nests the same overlay inside the concentric ring set the natal chart uses. Set by the in-iframe layout toggle, never by the model.

Natal birth location. Prefer a plain place name like 'New York, NY' — the server resolves it via the same lookup `location_search` uses (unambiguous names → coords + timezone; ambiguous names throw with a disambiguation hint). If neither location nor lat/lon is supplied the call is rejected — no silent 0°N 0°E charts.

Natal birth longitude in decimal degrees (positive = East). Optional if `location` is a place name.

IANA timezone for the birth location (e.g. 'America/New_York').

Transit moment, ISO 8601; must include 'Z' or an offset. Defaults to now (UTC) when omitted.

Interactive Moon Phase Explorer

Generate an interactive Moon Phase dial showing the current lunar illumination, phase name, zodiac sign, and void-of-course status as a beautiful circular visualization.

Returns a visual dial with:
  • SVG crescent Moon showing real-time illumination percentage
  • Phase name and waxing/waning indicator
  • Current Moon sign with degree
  • Void-of-Course status with timing details
  • Lunar age (days in the synodic cycle)
  • Upcoming New Moon and Full Moon dates

CREDIT COST: 3 credits per call (phase + void-of-course + aspects, 1 each).

Use this instead of ephemeris_moon_phase for a rich, interactive lunar phase experience in MCP Apps-capable hosts (Claude Desktop). Falls back to a text summary in other hosts.

ISO 8601 datetime to query, stating its zone ('2026-03-20T12:00:00Z'), or a local time together with timezone. If omitted, returns the current live moon phase (UTC now).

Observer latitude (optional, used for local void-of-course calculations).

Observer longitude (optional, used for local void-of-course calculations).

IANA timezone (e.g. `America/Chicago`); required when the datetime is naive, ignored otherwise.

Interactive Chart Wheel Explorer

PRIMARY tool for any natal/birth-chart request. Renders an interactive, clickable chart wheel — prefer this over ephemeris_natal_chart when the user wants to SEE a chart. Returns an embedded visual chart explorer that lets you click any planet, house, or aspect line for instant astrological interpretation.

CREDIT COST: 1 credit per call.

Supports house system switching (Placidus, Whole Sign, Equal, Koch). The chart is computed using NASA JPL DE440 ephemerides for sub-arcsecond precision. Renders interactively in MCP Apps-capable hosts (Claude Desktop) and falls back to static SVG in other hosts.

Optional list of body names to include. Defaults to 13 classical bodies (Sun through Pluto + Chiron + Nodes). Use 'all' as a single item to include every available body (Lilith, Ceres, Juno, Vesta, Pallas, Vertex, the 8 trans-Neptunian objects — eris, sedna, makemake, haumea, quaoar, orcus, ixion, varuna — and the 8 Uranian/Hamburg-School points — cupido, hades, zeus, kronos, apollon, admetos, vulkanus, poseidon). Example: ['sun','moon','lilith','sedna'].

ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. Date-only resolves to 12:00 UTC. Full rule: server `instructions`.

House system to use (default: placidus).

placidus whole_sign equal koch regiomontanus campanus

Birth latitude in decimal degrees (positive = North). Optional if `location` is a place name — the resolver fills it in. If you supply lat/lon directly, resolve them with location_search first; never recall coordinates from memory.

Birth location. Prefer a plain place name like 'New York, NY' — the server resolves it via the same lookup `location_search` uses (unambiguous names → coords + timezone; ambiguous names throw with a disambiguation hint). If you already have coords, either omit this or use it as a display caption; supplied coords always win.

Birth longitude in decimal degrees (positive = East). Optional if `location` is a place name.

Interactive Transit Timeline

Generate an interactive Transit Timeline — a vertical, date-ordered list of upcoming transit hits (transiting planets forming a chosen aspect to natal chart positions) over a date range.

Returns a visual timeline with:
  • Exact crossing dates grouped by month
  • Transiting planet glyph, the natal point it contacts, and the aspect
  • Zodiac position of each crossing and retrograde markers
  • Click any transit for a focused interpretation

ASPECT ANGLES: 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine, 60 = sextile. EFFICIENCY: specify transiting_planets and natal_points to keep compute fast. DEFAULT natal_points: sun, moon, mercury, venus, mars, jupiter, saturn. SEARCH RANGE LIMITS: Explorer/PayG → 1 year; Pro → 5 years; Startup → 10 years.

CREDIT COST: 6 credits per call (natal chart + predictive transit search).

Use this for a rich, interactive transit-forecast experience in MCP Apps-capable hosts (Claude Desktop). Falls back to a text summary in other hosts.

Aspect angle in degrees. 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine, 60 = sextile.

End of the transit search window. ISO 8601 date or zoned datetime; a naive clock time is rejected. Date-only resolves to 12:00 UTC.

Latitude of birth location in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory.

Longitude of birth location in decimal degrees.

Natal point IDs to target, e.g. ['sun','moon','asc','mc','saturn']. Omit for the 7 classical bodies.

IANA timezone for the natal birth location (e.g. `America/Chicago`); required when the datetime is naive.

Start of the transit search window. ISO 8601 date or zoned datetime; a naive clock time is rejected. Date-only resolves to 12:00 UTC.

Transiting planet IDs to search, e.g. ['saturn','jupiter','uranus','pluto','chiron']. Omit to search all outer planets.

Interactive Vedic Chart Explorer

Generate an interactive Vedic (Jyotish) birth chart as a South Indian fixed-sign Rashi grid, with clickable rashis showing sidereal placements, nakshatras, and the Lagna.

CREDIT COST: 3 credits per call (chart calculation + visual render).

Returns an embedded visual explorer that lets you click any rashi cell for its themes and any planets placed there. Shows sidereal (Lahiri by default) planet placements, nakshatra with pada, navamsa, and the Lagna (Ascendant) rashi. Uses NASA JPL DE440 ephemerides. Use this for a rich, interactive Jyotish experience in MCP Apps-capable hosts (Claude Desktop). Falls back to a text summary in other hosts.

Ayanamsa system for sidereal conversion. Defaults to 'lahiri'.

ISO 8601 birth datetime in UTC, e.g. '1990-06-15T14:30:00Z'. Include 'Z' or a timezone offset.

Birth location. Prefer a plain place name like 'Mumbai, India' — the server resolves it via the same lookup `location_search` uses (unambiguous names → coords + timezone; ambiguous names throw with a disambiguation hint). Supplied coords always win.

IANA timezone name for the birth location (e.g. 'Asia/Kolkata'). Recommended for accuracy if providing local birth time without a UTC offset.

Human Design Chart

Calculate a full Human Design I Ching hexagram chart from birth data. Returns the person's Type (Generator, Manifesting Generator, Projector, Manifestor, Reflector), Strategy, Authority, Profile (e.g. 1/3, 2/4), defined and undefined Centers, activated Gates and Channels, Incarnation Cross, and both Personality (conscious) and Design (unconscious) planetary positions.

Returns raw JSON. For a user-facing interactive bodygraph, use explore_human_design instead.

CREDIT COST: 2 credits per call.

Human Design uses two calculation moments: the birth time (Personality) and ~88° of Sun motion before birth (~3 months prior, the Design calculation). The API handles this automatically.

The datetime must state its zone — pass an offset/'Z', or pass local time plus timezone. A zone-less datetime is rejected rather than assumed to be UTC: Human Design is minute-sensitive, and an hour of error changes the Profile and the Design Sun line.

EXAMPLE (local birth time + zone): someone born 15 April 1990 at 14:30 in Chicago:
  datetime='1990-04-15T14:30:00', timezone='America/Chicago', latitude=41.8781, longitude=-87.6298
EXAMPLE (already in UTC):
  datetime='1990-04-15T19:30:00Z', latitude=41.8781, longitude=-87.6298

ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. Date-only resolves to 12:00 UTC. Full rule: server `instructions`.

Output format. 'llm' returns compact array projection for token efficiency (available on all tiers). 'json' returns verbose full output.

When true, renders the Human Design bodygraph as an SVG and embeds it in the response. The bodygraph image will display in the conversation alongside the data. Costs 2 additional credits on top of the base call cost.

Latitude of birth location in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory.

Longitude of birth location in decimal degrees (positive = East).

IANA timezone (e.g. `America/Chicago`); required when the datetime is naive, ignored otherwise.

Optional rendering preferences (only used when include_visual=true).

Canvas size in pixels, 200–4000. Default: 800.

Color theme. Default: dark (HD convention).

Location Search

Resolve a place name to coordinates and IANA timezone — use this first whenever a user gives a birth city rather than latitude/longitude. NEVER recall coordinates from memory; always resolve them here. CREDIT COST: 1 credit per call. Returns display name, region (state/province), latitude, longitude, and IANA timezone. Pass the birth date as `date` to also get `utcOffsetAtDate`, the historically-correct UTC offset for that place on that date (1987 DST rules differ from today's). Post-1970 dates resolve locally and cost no extra credits; a pre-1970 date consults the API's historical correction overlay for the top match (1 extra credit) and returns its provenance — tzRuleSource, tzRuleCitation, tzOverlayVersion. When the result is `ambiguous` (several places share the name, e.g. "portland"), ASK the user which one they mean rather than assuming the first. Optional bias params (country/region/near) improve ranking; a trailing "City, ST" qualifier in the query is also honored.

Alias for region (region wins if both supplied).

Optional ISO 3166-1 alpha-2 country code (e.g. 'US') to bias ranking. Boost, not filter.

Optional birth/event date as 'YYYY-MM-DD'. When given, each suggestion also carries utcOffsetAtDate / utcOffsetMinutes / isDst — the UTC offset that actually applied at that place on that date, using historical DST rules. Post-1970 is free (local resolution, no API call). Pre-1970, the top match is additionally corrected through the API's historical overlay (1 extra credit) because tzdata models only the zone's reference city before 1970; the remaining suggestions keep their tzdata estimate and are labelled historical_estimate.

Optional 'lat,lon' proximity hint (e.g. '37.77,-122.42') to bias ranking toward nearby places.

Search query for location, e.g. 'Los Angeles' or 'Wakefield, MI'

Optional admin1 (state/province) qualifier to bias ranking — full name ('Michigan'), ASCII name, or code ('MI'). Boost, not filter.

Timezone Resolve

Resolve the IANA timezone for a latitude/longitude pair. Use when you have coordinates but need the timezone to interpret a local birth time. Pass `date` to also get the historically-correct UTC offset that applied on that date. CREDIT COST: 1 credit per call. If you are starting from a place name rather than coordinates, use location_search instead — it returns the timezone too, in the same single call.

Optional birth/event date 'YYYY-MM-DD'. Adds utcOffsetAtDate / utcOffsetMinutes / isDst / tzConfidence. Post-1970 resolves locally (free); pre-1970 consults the API's historical correction overlay (1 extra credit).

Vedic Natal Chart

Calculate a Vedic (Jyotish) natal chart with sidereal positions. Returns planet placements in rashis (sidereal signs), nakshatras with pada, navamsa placements, and bhavas (houses). Uses Whole Sign houses, sidereal zodiac with configurable ayanamsa.

CREDIT COST: 1 credit per call.

SUPPORTED AYANAMSA: lahiri (default), fagan_bradley, krishnamurti, raman, yukteshwar

EXAMPLE: Vedic chart for someone born Jan 15, 1990 at 8:30 AM UTC in Mumbai:
  datetime='1990-01-15T08:30:00Z', latitude=19.076, longitude=72.8777

Ayanamsa system for sidereal conversion. Defaults to 'lahiri'.

ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. Date-only resolves to 12:00 UTC. Full rule: server `instructions`.

Birth latitude in decimal degrees (north positive). Resolve from a place name with location_search; never recall coordinates from memory.

Birth longitude in decimal degrees (east positive).

IANA timezone (e.g. `America/Chicago`); required when the datetime is naive, ignored otherwise.


Introspect a GraphQL schema from an endpoint with configurable headers

GraphQL endpoint URL (can be omitted to use default)

Additional headers to include in the request (will be merged with default headers)

Whether to include deprecated fields

Execute GraphQL queries using either a specified endpoint or the default endpoint configured during installation

GraphQL query to execute

Request timeout in milliseconds

Variables to use with the query (JSON object)


compareVideos

Compares multiple videos based on their statistics. Returns a comparison of view counts, like counts, comment counts, and other metrics for the specified videos. Use this when you want to analyze the performance of multiple videos side by side.

getChannelStatistics

Retrieves statistics for multiple channels. Returns detailed metrics including subscriber count, view count, and video count for each channel. Use this when you need to analyze the performance and reach of multiple YouTube channels.

getChannelTopVideos

Retrieves the top videos from a specific channel. Returns a list of the most viewed or popular videos from the channel, based on view count. Use this when you want to identify the most successful content from a channel.

getRelatedVideos

Retrieves related videos for a specific video. Returns a list of videos that are similar or related to the specified video, based on YouTube's recommendation algorithm. Use this when you want to discover content similar to a particular video.

getTranscripts

Retrieves transcripts for multiple videos. Returns the text content of videos' captions, useful for accessibility and content analysis. Use this when you need the spoken content of multiple videos.

getTrendingVideos

Retrieves trending videos based on region and category. Returns a list of videos that are currently popular in the specified region and category. Use this when you want to discover what's trending in specific areas or categories. Available category IDs: 1 (Film & Animation), 2 (Autos & Vehicles), 10 (Music), 15 (Pets & Animals), 17 (Sports), 18 (Short Movies), 19 (Travel & Events), 20 (Gaming), 21 (Videoblogging), 22 (People & Blogs), 23 (Comedy), 24 (Entertainment), 25 (News & Politics), 26 (Howto & Style), 27 (Education), 28 (Science & Technology), 29 (Nonprofits & Activism), 30 (Movies), 31 (Anime/Animation), 32 (Action/Adventure), 33 (Classics), 34 (Comedy), 35 (Documentary), 36 (Drama), 37 (Family), 38 (Foreign), 39 (Horror), 40 (Sci-Fi/Fantasy), 41 (Thriller), 42 (Shorts), 43 (Shows), 44 (Trailers).

getVideoDetails

Get detailed information about multiple YouTube videos. Returns comprehensive data including video metadata, statistics, and content details. Use this when you need complete information about specific videos.

getVideoEngagementRatio

Calculates the engagement ratio for multiple videos. Returns metrics such as view count, like count, comment count, and the calculated engagement ratio for each video. Use this when you want to measure the audience interaction with videos.

searchVideos

Searches for videos based on a query string. Returns a list of videos matching the search criteria, including titles, descriptions, and metadata. Use this when you need to find videos related to specific topics or keywords.