{
  "markdown": "# OpenEphemeris MCP Server\n\n[![smithery badge](https://smithery.ai/badge/open-ephemeris/openephemeris)](https://smithery.ai/servers/open-ephemeris/openephemeris)\n[![npm version](https://img.shields.io/npm/v/@openephemeris/mcp-server)](https://www.npmjs.com/package/@openephemeris/mcp-server)\n[![System Status](https://img.shields.io/badge/Status-Operational-brightgreen)](https://status.openephemeris.com/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue)](LICENSE)\n[![Ephemeris: JPL DE440](https://img.shields.io/badge/Ephemeris-JPL%20DE440-6f42c1)](https://ssd.jpl.nasa.gov/planets/eph_export.html)\n\n![OpenEphemeris in Claude — ask in plain language, get a real computed chart](https://raw.githubusercontent.com/openephemeris/openephemeris-MCP/main/assets/hero-demo.gif)\n\nModel Context Protocol server for OpenEphemeris — typed astrology tools powered by the NASA JPL DE440 ephemeris. Zero hallucination on planetary positions, dates, and degrees. Covers 1,100 years of astronomical data.\n\n![The catalog: 90 bodies and 124 fixed stars — asteroids, trans-Neptunians, Uranian points, computed in one engine](https://raw.githubusercontent.com/openephemeris/openephemeris-MCP/main/assets/catalog-90-bodies.png)\n\n**Hosted endpoint:** `https://mcp.openephemeris.com/mcp` (Streamable HTTP, MCP 2025-11-25 spec)\n\n## Quick Start\n\n### Install via Smithery (recommended)\n\nThe fastest way to connect any MCP-compatible client:\n\n```bash\nnpx -y @smithery/cli install @open-ephemeris/openephemeris --client claude\n```\n\nOr browse the listing and copy connection snippets: **[smithery.ai/servers/open-ephemeris/openephemeris](https://smithery.ai/servers/open-ephemeris/openephemeris)**\n\n---\n\n### Connect via AI SDK (Vercel AI SDK)\n\n```typescript\nimport Smithery from \"@smithery/api\"\nimport { createMCPClient } from \"@ai-sdk/mcp\"\nimport { generateText } from \"ai\"\nimport { anthropic } from \"@ai-sdk/anthropic\"\nimport { createConnection } from \"@smithery/api/mcp\"\n\nconst smithery = new Smithery()\n\nconst conn = await smithery.connections.create(\"{your-namespace}\", {\n  mcpUrl: \"https://server.smithery.ai/open-ephemeris/openephemeris\",\n  headers: {\n    apiKey: \"your-openephemeris-api-key\", // get one free at openephemeris.com/dashboard\n  },\n})\n\nconst { transport } = await createConnection({\n  client: smithery,\n  namespace: \"{your-namespace}\",\n  connectionId: conn.connectionId,\n})\n\nconst mcpClient = await createMCPClient({ transport })\nconst tools = await mcpClient.tools()\n\nconst { text } = await generateText({\n  model: anthropic(\"claude-sonnet-4-20250514\"),\n  tools,\n  prompt: \"Calculate a natal chart for someone born April 15, 1990 at 2:30 PM in Chicago.\",\n})\n\nawait mcpClient.close()\n```\n\n### Connect via MCP SDK (TypeScript)\n\n```typescript\nimport Smithery from \"@smithery/api\"\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\"\nimport { createConnection } from \"@smithery/api/mcp\"\n\nconst smithery = new Smithery()\n\nconst conn = await smithery.connections.create(\"{your-namespace}\", {\n  mcpUrl: \"https://server.smithery.ai/open-ephemeris/openephemeris\",\n  headers: {\n    apiKey: \"your-openephemeris-api-key\",\n  },\n})\n\nconst { transport } = await createConnection({\n  client: smithery,\n  namespace: \"{your-namespace}\",\n  connectionId: conn.connectionId,\n})\n\nconst mcpClient = new Client(\n  { name: \"my-app\", version: \"1.0.0\" },\n  { capabilities: {} }\n)\nawait mcpClient.connect(transport)\n\nconst { tools } = await mcpClient.listTools()\nconst result = await mcpClient.callTool({\n  name: \"ephemeris_natal_chart\",\n  // A datetime that states a clock time must state its zone: either pass\n  // `timezone` alongside the local time, or put a Z/±HH:MM offset on the value.\n  arguments: {\n    datetime: \"1990-04-15T14:30:00\",\n    timezone: \"America/Chicago\",\n    latitude: 41.8781,\n    longitude: -87.6298,\n    format: \"llm\",\n  },\n})\n```\n\n### Connect directly (Streamable HTTP, no Smithery)\n\n```typescript\nimport { StreamableHTTPClientTransport } from \"@modelcontextprotocol/sdk/client/streamableHttp.js\"\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\"\n\nconst transport = new StreamableHTTPClientTransport(\n  new URL(\"https://mcp.openephemeris.com/mcp\"),\n  { requestInit: { headers: { \"X-API-Key\": \"your-openephemeris-api-key\" } } }\n)\n\nconst client = new Client({ name: \"my-app\", version: \"1.0.0\" }, { capabilities: {} })\nawait client.connect(transport)\n```\n\n---\n\n### One-click install (Cursor)\n\n<!-- GENERATED:CURSOR_INSTALL:BEGIN -->\n[![Install in Cursor](https://img.shields.io/badge/Install%20in-Cursor-1f6feb)](cursor://anysphere.cursor-deeplink/mcp/install?name=openephemeris&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBvcGVuZXBoZW1lcmlzL21jcC1zZXJ2ZXIiXSwiZW52Ijp7Ik9QRU5FUEhFTUVSSVNfUFJPRklMRSI6ImRldiIsIk9QRU5FUEhFTUVSSVNfQkFDS0VORF9VUkwiOiJodHRwczovL2FwaS5vcGVuZXBoZW1lcmlzLmNvbSIsIk9QRU5FUEhFTUVSSVNfQVBJX0tFWSI6IllPVVJfQVBJX0tFWV9IRVJFIn19)\n\n> Replace `YOUR_API_KEY_HERE` in Cursor MCP settings with your API key from https://openephemeris.com/dashboard.\n\nCursor deeplink payload:\n```json\n{\n  \"command\": \"npx\",\n  \"args\": [\n    \"-y\",\n    \"@openephemeris/mcp-server\"\n  ],\n  \"env\": {\n    \"OPENEPHEMERIS_PROFILE\": \"dev\",\n    \"OPENEPHEMERIS_BACKEND_URL\": \"https://api.openephemeris.com\",\n    \"OPENEPHEMERIS_API_KEY\": \"YOUR_API_KEY_HERE\"\n  }\n}\n```\n<!-- GENERATED:CURSOR_INSTALL:END -->\n\n### Manual install (stdio MCP clients)\n\n```json\n{\n  \"mcpServers\": {\n    \"openephemeris\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@openephemeris/mcp-server\"],\n      \"env\": {\n        \"OPENEPHEMERIS_PROFILE\": \"dev\",\n        \"OPENEPHEMERIS_BACKEND_URL\": \"https://api.openephemeris.com\",\n        \"OPENEPHEMERIS_API_KEY\": \"YOUR_API_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n\n### Platform guide\n\n> **Detailed setup walkthroughs** for each platform are in [SETUP.md](./SETUP.md).\n\n| Client | Install mode | Config location |\n|---|---|---|\n| Smithery | One-click | [smithery.ai](https://smithery.ai/servers/open-ephemeris/openephemeris) |\n| Cursor | One-click deeplink or manual | `~/.cursor/mcp.json` |\n| Claude Desktop (macOS) | Manual | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Claude Desktop (Windows) | Manual | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Windsurf | Manual | `~/.codeium/windsurf/mcp_config.json` (or legacy `~/.codeium/mcp_config.json`) |\n| Claude Web / ChatGPT / remote clients | Hosted URL | `https://mcp.openephemeris.com/mcp` |\n\n### Client install walkthroughs\n\n1. Cursor\n   - Click the \"Install in Cursor\" button above, then replace `YOUR_API_KEY_HERE` in Cursor MCP settings.\n   - If you prefer manual setup, paste the `mcpServers.openephemeris` block from \"Manual install\" into `~/.cursor/mcp.json`.\n2. Claude Desktop (macOS/Windows)\n   - Open the platform config file from the table above.\n   - Add the same `mcpServers.openephemeris` block from \"Manual install\".\n   - Restart Claude Desktop.\n3. Windsurf\n   - Open `~/.codeium/windsurf/mcp_config.json` (or the legacy `~/.codeium/mcp_config.json` path).\n   - Add the `mcpServers.openephemeris` block from \"Manual install\".\n   - Restart Windsurf.\n\n### Remote-only clients (Claude Web, ChatGPT, etc.)\n\nThe server is hosted at `https://mcp.openephemeris.com/mcp` with full Streamable HTTP support (MCP 2025-11-25 spec). Remote-only clients can connect directly — no bridge/proxy required:\n\n- **Claude Web**: Add `https://mcp.openephemeris.com/mcp` as a custom connector URL — leave OAuth Client ID and Secret **blank**. The server uses OAuth 2.1 + PKCE (Dynamic Client Registration), so Claude handles authentication via a browser popup automatically.\n- **ChatGPT**: OpenEphemeris is not in the ChatGPT app directory — you add it yourself.\n  Turn on **Settings → Plugins → Advanced → Developer mode**, then use the **+ (Create app)**\n  button on [chatgpt.com/plugins](https://chatgpt.com/plugins). Server URL:\n  `https://mcp.openephemeris.com/mcp` (append `?profile=core` for the curated 39-tool\n  surface, which still includes every interactive chart). Leave Authentication on **OAuth**;\n  the same PKCE + Dynamic Client Registration flow applies, so there is no client ID or\n  secret to enter. Charts render inline, exactly as they do in Claude. *Developer mode was\n  available on a Free plan when this was last checked (2026-09-04); availability may vary.*\n- **Via Smithery**: Use the [Smithery listing](https://smithery.ai/servers/open-ephemeris/openephemeris) for managed connections with any client\n- **Legacy SSE**: retired in 3.20.0 — use Streamable HTTP at `/mcp`\n\n### Auth and upgrade behavior in MCP clients\n\n- Missing/invalid credentials (`401`): tool call fails with a message that points users to sign up/sign in at `https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount`, then create/manage keys in `https://openephemeris.com/dashboard?tab=account`.\n- Tier-gated endpoint (`403`): tool call returns an upgrade-required message with `https://openephemeris.com/pay` and dashboard billing/key management link.\n- Monthly quota exhausted (`402`): tool call returns usage quota guidance with both dashboard (`/dashboard?tab=account`) and upgrade (`/pay`) links.\n- Burst/rate limit (`429`): tool call returns retry guidance and links to dashboard usage monitoring.\n\n## What You Can Ask\n\n```\n\"Calculate a natal chart for 1990-04-15 at 2:30 PM in Chicago.\"\n\"Find all Saturn transits to my natal Sun in the next 6 months.\"\n\"Get the current moon phase and void-of-course status.\"\n\"Find the next solar eclipse visible from Tokyo.\"\n\"Find the best time to sign a contract in March — electional window.\"\n\"Generate a Human Design chart for my birth data.\"\n\"What is my Vedic (sidereal) chart?\"\n\"Calculate my Chinese BaZi (Four Pillars) chart.\"\n\"Show me my Astrocartography power lines — where is my Venus line on the map?\"\n\"Find all ACG lines within 3° of Paris for my chart.\"\n\"Calculate a synastry chart between two people.\"\n\"Find the next Venus Star Point and my relationship to it.\"\n\"What are the active planetary stations in the next 3 months?\"\n\"Calculate primary directions for the next 5 years.\"\n\"Find my Firdaria time lord period.\"\n\"What is the sidereal time and delta-T right now?\"\n```\n\n## Interactive Charts\n\nNine of the tools don't answer with JSON. They open a chart in the conversation — a real one, drawn from the same calculation, that you can click around in.\n\nThis matters more than it sounds. A natal chart returned as JSON is a list of numbers you have to already understand to read. The same chart rendered as a wheel is something you can point at. Click a planet and you get that placement explained; click a house and you get what's in it. The chart stays on screen while you keep talking, and it doesn't cost another credit to keep looking at it.\n\nThese need a host that supports MCP Apps. **Claude and ChatGPT both do**, and they render\nthe same widget — there is no separate ChatGPT build. MCP Apps ([SEP-1865][sep1865]) was\nco-authored by Anthropic and OpenAI and became the first official MCP extension in January\n2026, so one `ui://` resource serves both. In ChatGPT you add the server yourself as a\ncustom app (see [Setup](#setup)); OpenEphemeris is not in the ChatGPT app directory.\n\nIn a client without app support the same tools still work; you get the underlying data\ninstead of the picture, so nothing breaks, you just don't get the wheel.\n\n[sep1865]: https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp\n\n| Tool | What opens | What you can click | Credits |\n|---|---|---|---|\n| `explore_natal_chart` | Natal wheel — planets, houses, aspects, angles | Planets, houses, aspect lines; recalculate with new settings | 1 |\n| `explore_bi_wheel` | Two charts on one wheel: transits, synastry, progressions | Either wheel's planets, houses, and the aspects between them | 2 |\n| `explore_human_design` | Human Design bodygraph, with a mandala view toggle | Centers, gates, channels, planets, variables | 2 |\n| `explore_human_design_transit` | Today's planets laid over a natal bodygraph | Transit-activated channels | 3 |\n| `explore_human_design_connection` | Two bodygraphs combined, every shared channel classified | Connection channels by type | 3 |\n| `explore_vedic_chart` | South Indian Rashi grid — sidereal placements and Lagna | Each rashi, for its placements and nakshatras | 3 |\n| `explore_bazi_chart` | Four Pillars (四柱命盘) — Year, Month, Day, Hour | Each pillar | 3 |\n| `explore_transit_timeline` | Upcoming transit hits in date order | Individual hits | 6 |\n| `explore_moon_phase` | Moon dial — illumination, phase, sign, void-of-course | Recalculate for another moment | 3 |\n\nAsk for these the way you'd ask a person: *\"show me my chart\"*, *\"put today's transits over my Human Design\"*, *\"what's the moon doing right now\"*. The model picks the app.\n\nTwo things worth knowing. The chart wheel and bi-wheel accept a click on an aspect line, not just on the two planets it joins — so \"why does this line matter\" is one click rather than a paragraph of setup. And the bodygraph's mandala toggle rearranges the whole chart into concentric rings without another API call, so switching views is free.\n\nScreenshots of each are on the way.\n\n## Tools at a Glance\n\n| Category | Tool | Tier |\n|---|---|---|\n| Natal chart | `ephemeris_natal_chart` | Explorer |\n| Transit forecast | `ephemeris_transits` | Explorer |\n| Transit chart snapshot | `ephemeris_natal_transits` | Explorer |\n| Moon phase / VOC | `ephemeris_moon_phase` | Explorer |\n| Eclipse next visible | `ephemeris_next_eclipse` | Explorer |\n| Electional window | `ephemeris_electional` | Developer |\n| Moment analysis | `electional_moment_analysis` | Developer |\n| Station tracker | `electional_station_tracker` | Developer |\n| Aspect search | `electional_aspect_search` | Developer |\n| Human Design chart | `human_design_chart` | Explorer |\n| HD composite | `human_design_composite` | Developer |\n| HD transit overlay | `explore_human_design_transit` | Developer |\n| HD connection (synastry) | `explore_human_design_connection` | Developer |\n| HD penta | `human_design_penta` | Explorer |\n| HD return / opposition | `hd_planetary_return`, `hd_opposition` | Explorer |\n| Vedic chart | `vedic_chart` | Explorer |\n| BaZi (Chinese) | `chinese_bazi` | Explorer |\n| Synastry | `ephemeris_synastry` | Developer |\n| Composite chart | `ephemeris_composite` | Developer |\n| Relocation chart | `ephemeris_relocation` | Developer |\n| Progressed chart | `ephemeris_progressed_chart` | Explorer |\n| Solar return | `ephemeris_solar_return` | Developer |\n| Lunar return | `ephemeris_lunar_return` | Developer |\n| Planetary return | `ephemeris_planetary_return` | Developer |\n| Astrocartography lines | `acg_power_lines` | Developer |\n| ACG hits at location | `acg_hits` | Scale |\n| Venus Star Points | `venus_star_points` + 4 more | Explorer |\n| Chart wheel image | `ephemeris_chart_wheel` | Developer |\n| Bi-wheel image | `ephemeris_bi_wheel` | Developer |\n| Dignities / Midpoints / Fixed stars | `ephemeris_dignities`, `ephemeris_midpoints`, `ephemeris_fixed_stars` | Explorer |\n\n## Tooling Model\n\n- Typed tools are preferred for common workflows (natal, transits, moon phase, eclipse, synastry, relocation, electional, Human Design).\n- Generic tools: `dev_list_allowed` returns all currently allowlisted operations; `dev_read_api` invokes allowlisted **GET** (read) operations and `dev_write_api` invokes allowlisted **POST/PUT/PATCH/DELETE** (write/compute) operations, each by `method + path`. Read and write are kept as separate tools so a safe read surface never shares a tool with state-changing writes.\n- Security model: default-deny with explicit allowlist in `config/dev-allowlist.json`.\n- Deny prefixes block sensitive route families (`/auth`, `/billing`, `/admin`, etc.).\n\n### `dev_read_api` / `dev_write_api` input\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `method` | `dev_read_api`: `GET` · `dev_write_api`: `POST\\|PUT\\|PATCH\\|DELETE` | No | HTTP method (defaults to the tool's natural method) |\n| `path` | `string` | Yes | Absolute API path, e.g. `/ephemeris/natal-chart` |\n| `query` | `object` | No | Query parameters |\n| `body` | `object` | No | JSON body for non-GET requests |\n| `preset` | `full\\|simple` | No | Convenience mapping to `query.preset` |\n| `format` | `json\\|llm\\|llm_v2` | No | Convenience mapping to `query.format` (`llm_v2` normalizes to `llm`) |\n| `output_mode` | `full\\|simple\\|llm\\|llm_v2` | No | Legacy compatibility field |\n\n## Environment Variables\n\n| Variable | Required | Description |\n|---|---|---|\n| `OPENEPHEMERIS_API_KEY` | Yes (unless service key/JWT used) | API key for OpenEphemeris |\n| `ASTROMCP_API_KEY` | No | Legacy alias for `OPENEPHEMERIS_API_KEY` (checked as fallback) |\n| `OPENEPHEMERIS_BACKEND_URL` | No | Defaults to `https://api.openephemeris.com` |\n| `OPENEPHEMERIS_PROFILE` | No | `dev` by default |\n| `OPENEPHEMERIS_TOOLS` | No | `core` (default) advertises a focused everyday tool set; `full` advertises every tool. See [Tool surface](#tool-surface) |\n| `OPENEPHEMERIS_TELEMETRY` | No | Set to `0`/`false`/`off` to disable anonymous usage reporting. `DO_NOT_TRACK=1` also works. See [Telemetry](#telemetry) |\n| `OPENEPHEMERIS_SERVICE_KEY` | No | Internal service auth |\n| `OPENEPHEMERIS_JWT` | No | Bearer token auth |\n| `OPENEPHEMERIS_DEV_ALLOWLIST_PATH` | No | Override allowlist file path |\n| `MCP_USER_ID` | No | Per-instance user identifier |\n\nLegacy aliases (`ASTROMCP_*`, `MERIDIAN_*`) remain supported.\n\n## Telemetry\n\nThis server reports anonymous usage so we know which tools are worth maintaining and which are broken. Three events: session start, tool call, tool error.\n\n**What is sent:** the tool name, how long it took, error status, which MCP client connected (e.g. Claude Desktop, Cursor) and its version, the server version, and a one-way SHA-256 prefix of your API key used as a stable anonymous id.\n\n**What is never sent:** your API key or token, birth data, dates, names, coordinates, tool arguments, or tool results. No request or response bodies, ever.\n\n**To turn it off** — either works, checked before anything is sent:\n\n```bash\nOPENEPHEMERIS_TELEMETRY=0\n# or the cross-tool standard\nDO_NOT_TRACK=1\n```\n\n## Tool surface\n\nBy default the server advertises a **focused core set** of everyday tools rather than the entire catalog. Large tool lists cost context and make model tool-selection worse, so the default is tuned for real conversations: one interactive app per tradition, the primary data tool per domain, geocoding, and the allowlist-gated generic proxy.\n\n**Nothing is removed.** The surface is a filter on `tools/list` only — every tool stays registered and stays callable by name. If you know the tool you want, call it and it works, listed or not.\n\nTo advertise the full catalog:\n\n```bash\nOPENEPHEMERIS_TOOLS=full npx -y @openephemeris/mcp-server\n```\n\nOn the remote HTTP server, append `?profile=full` to the connector URL (or send `X-OE-Tool-Surface: full`):\n\n```\nhttps://mcp.openephemeris.com/mcp?profile=full\n```\n\n### Toolsets by tradition\n\nIf you work in one tradition, ask for it by name instead of taking the general-purpose default. You get that tradition in full — including the long-tail tools the core set leaves out — for a fraction of the context.\n\n```bash\nOPENEPHEMERIS_TOOLS=hd npx -y @openephemeris/mcp-server        # Human Design\nOPENEPHEMERIS_TOOLS=astrology,moon npx -y @openephemeris/mcp-server\n```\n\n```\nhttps://mcp.openephemeris.com/mcp?profile=hd,bazi\n```\n\n| Toolset | What it covers | Tools | Approx. tokens |\n|---|---|---:|---:|\n| `astrology` | Natal, transits, synastry, progressions, returns, relocation, dignities, midpoints, lots, fixed stars, composites | 32 | 15,800 |\n| `hd` | Human Design charts, transits, connection charts, penta, bodygraph | 14 | 7,800 |\n| `bazi` | Four Pillars, Ten Gods, element balance, luck pillars, compatibility | 13 | 7,200 |\n| `electional` | Timing windows, angle crossings, stations, moment analysis | 10 | 4,600 |\n| `moon` | Phases, void-of-course, eclipses | 9 | 4,100 |\n| `venus` | Star points, phases, elongations, stations | 11 | 3,700 |\n| `acg` | Astrocartography lines and hits | 7 | 3,700 |\n| `vedic` | Jyotish Rashi chart | 7 | 3,400 |\n| — | *core (default)* | 36 | 19,100 |\n| — | *full* | 70 | 34,600 |\n\nEvery selection also includes geocoding (`location_search`, `timezone_resolve`), `account_usage`, and the allowlist-gated proxy — so a birthplace is always resolvable and nothing is stranded.\n\nCombine with commas; unknown names are ignored rather than rejected, so a typo degrades to a smaller surface instead of a dead connector. As with `core`/`full`, this only filters `tools/list` — every tool remains callable by name.\n\nWhy it matters: tool definitions are re-sent to the model on **every** pass. `astrology,moon` advertises the same number of tools as the default but costs ~1,700 fewer tokens per message and covers more of the tradition.\n\nThe surface is fixed when the session initializes — this server does not advertise `tools.listChanged`, so switching requires reconnecting. `dev_list_allowed` enumerates every operation reachable through the generic proxy regardless of surface.\n\n## Contributing & Support\n\n- **Something wrong with a result?** [Open an issue](https://github.com/openephemeris/openephemeris-MCP/issues/new/choose) — include the tool, your inputs, and what you expected.\n- **Want to contribute?** See [CONTRIBUTING.md](CONTRIBUTING.md). Integration examples and new skills are the most useful things you can add.\n- **Found a security problem?** Please report it privately — see [SECURITY.md](SECURITY.md).\n- **Tools timing out?** Check [status.openephemeris.com](https://status.openephemeris.com) first.\n\nIf this saved you from an LLM confidently inventing a Saturn position, a ⭐ helps other people find it.\n\n## Legal\n\nThis package is licensed under the [MIT License](./LICENSE). However, use of this package to access the OpenEphemeris API constitutes use of the Service and is governed by the [OpenEphemeris Terms of Service](https://openephemeris.com/terms). By using this package, you agree to those terms. See also the [Privacy Policy](https://openephemeris.com/privacy) and [Acceptable Use Policy](https://openephemeris.com/acceptable-use).\n\n## Development\n\n```bash\nnpm install\nnpm run dev\nnpm run typecheck\nnpm test\nnpm run regen:dev-allowlist\nnpm run check:dev-allowlist\nnpm run sync:readme\nnpm run check:readme\nnpm run verify:release\n```\n\n### Deploying the SSE Server to Fly.io\n\nWhen you update the MCP server logic (handlers, bug fixes, hardening), you should deploy it so clients connecting via the remote `https://mcp.openephemeris.com/mcp` endpoint get the updates immediately.\n\n1. Navigate to `apps/api/mcp-server`\n2. Run `fly deploy --remote-only`\n\n*Note on NPM:* Deploying to Fly.io instantly updates the web-accessible SSE tool. However, users installing your tool locally in Cursor/Desktop via `npx @openephemeris/mcp-server` will *only* receive the updates once a new version is published to NPM. If your changes are critical, you should bump the version in `package.json` and run `npm publish` (or your CI release pipeline) *after* deploying to Fly.\n\n`npm run verify:release` is the release gate. It checks:\n- allowlist freshness against OpenAPI\n- schema pack freshness\n- README synchronization\n- type safety + tests\n- publish tarball contents (`npm pack --dry-run --json`)\n\n## Architecture\n\n```text\n┌─────────────────────────────────────────────────────────┐\n│                    MCP Clients                          │\n│  Smithery Gateway · Claude Web · ChatGPT · Remote apps  │\n└──────────────────┬──────────────────────────────────────┘\n                   │ Streamable HTTP (MCP 2025-11-25)\n                   │ https://mcp.openephemeris.com/mcp\n                   │\n┌─────────────────────────────────────────────────────────┐\n│          Cursor · Claude Desktop · Windsurf             │\n└──────────────────┬──────────────────────────────────────┘\n                   │ stdio JSON-RPC\n                   │ npx @openephemeris/mcp-server\n                   │\n              ┌────▼────────────────────┐\n              │  openephemeris-mcp      │\n              │  Node.js MCP Server     │\n              │  typed tools            │\n              │  auth: Key > JWT        │\n              └────────────┬────────────┘\n                           │ HTTPS\n                           ▼\n              ┌────────────────────────┐\n              │  OpenEphemeris API     │\n              │  api.openephemeris.com │\n              │  NASA JPL DE440        │\n              │  1,100 years of data   │\n              └────────────────────────┘\n```\n\n<!-- GENERATED:RUNTIME_SNAPSHOT:BEGIN -->\n## Runtime Snapshot (Generated)\n\nGenerated by `npm run sync:readme` from `config/dev-allowlist.json` and the live tool registry.\n\n- Allowlisted operations: **120**\n- Methods: `GET=44`, `POST=76`, `PUT=0`, `PATCH=0`, `DELETE=0`\n- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **92**\n- Typed tools: `account_usage`, `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `bazi_annual_pillar`, `bazi_chart`, `bazi_compatibility`, `bazi_element_balance`, `bazi_luck_pillars`, `bazi_recalculate`, `bazi_ten_gods`, `bi_wheel_on_cross_aspect_click`, `bi_wheel_on_house_click`, `bi_wheel_on_planet_click`, `bi_wheel_recalculate`, `bi_wheel_synopsis`, `bodygraph_recalculate`, `chart_wheel_on_aspect_click`, `chart_wheel_on_house_click`, `chart_wheel_on_planet_click`, `chart_wheel_recalculate`, `chinese_bazi`, `electional_angle_crossings`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `explore_bazi_chart`, `explore_bi_wheel`, `explore_human_design`, `explore_human_design_connection`, `explore_human_design_transit`, `explore_moon_phase`, `explore_natal_chart`, `explore_transit_timeline`, `explore_vedic_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_connection_channel_click`, `hd_on_gate_click`, `hd_on_planet_click`, `hd_on_transit_channel_click`, `hd_on_variable_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `location_search`, `moon_phase_recalculate`, `timezone_resolve`, `vedic_chart`, `vedic_chart_recalculate`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`\n- Generic tools: `dev_list_allowed`, `dev_read_api`, `dev_write_api`\n\n### Allowlist Families\n\n| Family | Operations | Example |\n|---|---:|---|\n| `acg` | 14 | `POST /acg/aspects`, `POST /acg/ccg` |\n| `calendar` | 3 | `GET /calendar/astrology/cross-quarter`, `GET /calendar/astrology/lunar-standstill` |\n| `catalogs` | 3 | `GET /catalogs/bodies`, `GET /catalogs/fixed-stars` |\n| `chinese` | 9 | `POST /chinese/bazi`, `POST /chinese/bazi/annual-pillar` |\n| `comparative` | 5 | `POST /comparative/composite`, `POST /comparative/composite/midpoint` |\n| `eclipse` | 6 | `GET /eclipse/besselian-elements`, `GET /eclipse/lunar/global` |\n| `electional` | 6 | `GET /electional/angle-crossings`, `GET /electional/aspect-search` |\n| `ephemeris` | 36 | `GET /ephemeris/agro/calendar`, `GET /ephemeris/agro/daily` |\n| `health` | 2 | `GET /health`, `GET /health/detailed` |\n| `human-design` | 8 | `POST /human-design/chart`, `POST /human-design/composite` |\n| `location` | 2 | `GET /location/autocomplete`, `GET /location/reverse` |\n| `predictive` | 10 | `POST /predictive/returns`, `POST /predictive/returns/lunar` |\n| `root` | 1 | `GET /` |\n| `tidal` | 2 | `GET /tidal/forcing`, `GET /tidal/forcing/deep-time` |\n| `time` | 6 | `GET /time/delta-t`, `GET /time/equation-of-time` |\n| `timezone` | 3 | `GET /timezone/coverage`, `POST /timezone/lookup` |\n| `vedic` | 1 | `POST /vedic/chart` |\n| `visualization` | 3 | `POST /visualization/bi-wheel`, `POST /visualization/bodygraph` |\n<!-- GENERATED:RUNTIME_SNAPSHOT:END -->\n\n## Why OpenEphemeris for AI Agents?\n\nMost LLMs (like Claude and ChatGPT) struggle heavily with astronomical calculations (trigonometry, Julian date conversions, and planetary lookups). OpenEphemeris serves as a **secure, remote math engine**.\n\nBy pairing LLMs with the OpenEphemeris MCP server, your agents can instantly access:\n- **Zero-hallucination coordinates**: Direct, sub-arcsecond NASA JPL DE440 calculations spanning 1,100 years of astronomical data.\n- **LLM-optimized tokens (`format=llm`)**: We compress standard 25,000 token JSON chart responses into minimal text blocks, cutting your inference costs by 50–73% depending on endpoint.\n- **Ready-to-use astrology layers**: Built-in support for Astrocartography geoJSON lines, Hermetic Lots, Fixed Stars, and complex Human Design matrix generation.",
  "bytes": 29440,
  "sha": "a476fbba3e8c22fc9e4f80505694cfc5c32e842f556d50dde3f007ae917b95cd",
  "repo_slug": "openephemeris/openephemeris-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_openephemeris_open_ephemeris_9154e01e/readme"
}