Model Context Protocol

Use the Occult API from your AI assistant

Connect Claude, Cursor or any MCP-compatible assistant to real ephemeris data. Ask for a panchanga, a kundli or a dasha in plain language and get an actual calculation back — not a plausible-looking invention.

you:  What's the panchanga for Jaipur tomorrow at sunrise?

      → tithi Chaturthi (Krishna paksha), yoga Vriddhi, karana Balava

Before you start

You need an API key. Create an account and make one from the Keys page — it is shown once, so copy it before you leave. Node 18 or newer is the only other requirement, and npx downloads the rest on first run.

Set it up

Every client uses the same block. Add it to the file below — if the file already has an mcpServers section, put occult-api inside it rather than adding a second one.

{
  "mcpServers": {
    "occult-api": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "occult-api-mcp"],
      "env": { "OCCULT_API_KEY": "yt_live_your_key_here" }
    }
  }
}

Claude Code (VS Code)~/.claude.jsonC:Users<you>.claude.json on Windows

Claude Desktopclaude_desktop_config.json%APPDATA%Claude on Windows, ~/Library/Application Support/Claude/ on macOS

Cursor~/.cursor/mcp.json

Then restart the app completely. MCP servers are connected at startup, so reloading the window is not enough.

Or, from the terminal

If you have the Claude Code command line installed, this does the same thing in one step. It will not work in the VS Code extension, which has no claude command — use the config file above instead.

claude mcp add occult-api -e OCCULT_API_KEY=yt_live_your_key_here -- npx -y occult-api-mcp

What the assistant can do

Five tools, covering all 130 endpoints and 417 calculations. There is deliberately not one tool per endpoint: every tool sits in the model's context on every message, and ninety of them would crowd out the conversation before you asked anything. It searches instead.

check_accountFree

Confirms the key works and reports the credit balance. Ask the assistant to run this first if anything fails — it separates a bad key from an empty balance.

search_endpointsFree

Finds a calculation by name or by feature. 'manglik' resolves even though no endpoint is called that — it searches every named calculation, not just endpoint names.

describe_endpointFree

The exact request fields, the values each one accepts, and a request body proven against a live server.

call_endpoint1 credit

Runs any endpoint. Failed requests are not charged.

get_panchanga1 credit

A named shortcut for the most common request, so the assistant does not have to look it up first.

What it costs

Exactly what a direct HTTP call costs: one credit per successful calculation, nothing for a failed request. Searching and reading the documentation are free, so an assistant can explore the whole API without spending anything. The balance comes back with every call and you get a warning below 50 credits.

About your key

The key stays on your machine. It is read from the environment, sent to the API as a header, and never shown to the model — the assistant sees results, never the credential.

It is still a server-side credential: anyone holding it can spend your credits. Keep it out of shared configs and repositories, and rotate it from the Keys page if you think it has leaked.

If something goes wrong

"Your Occult API key is invalid, revoked, or expired": Create a new key, update the env block and restart the app. MCP servers read their environment once, at startup.
"claude" is not recognized as a command: You are using the VS Code extension, which does not install a claude command. Use the config file above — it does exactly the same thing.
The server does not appear at all: Check the JSON is valid, then restart the app completely. Startup errors go to the client's MCP log, not to the chat.
The assistant cannot find a calculation: Try the Sanskrit name — "kundli" rather than "birth chart". Every calculation is listed in the reference.

Get an API key View on npm Source on GitHub