npm package: @openephemeris/mcp-server
Description: Model Context Protocol server for the Open Ephemeris astronomical computation API
Author: Open Ephemeris
Latest version: 3.5.3

# OpenEphemeris MCP Server

[![System Status](https://img.shields.io/badge/Status-Operational-brightgreen)](https://status.openephemeris.com/)

Model Context Protocol server for OpenEphemeris. This package exposes typed astrology tools and an allowlist-gated generic proxy (`dev.call`) for MCP-compatible clients.

## Quick Start

### One-click install (Cursor)

<!-- GENERATED:CURSOR_INSTALL:BEGIN -->
[![Install in Cursor](https://img.shields.io/badge/Install%20in-Cursor-1f6feb)](cursor://anysphere.cursor-deeplink/mcp/install?name=openephemeris&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBvcGVuZXBoZW1lcmlzL21jcC1zZXJ2ZXIiXSwiZW52Ijp7Ik9QRU5FUEhFTUVSSVNfUFJPRklMRSI6ImRldiIsIk9QRU5FUEhFTUVSSVNfQkFDS0VORF9VUkwiOiJodHRwczovL2FwaS5vcGVuZXBoZW1lcmlzLmNvbSIsIk9QRU5FUEhFTUVSSVNfQVBJX0tFWSI6IllPVVJfQVBJX0tFWV9IRVJFIn19)

> Replace `YOUR_API_KEY_HERE` in Cursor MCP settings with your API key from https://openephemeris.com/dashboard.

Cursor deeplink payload:
```json
{
  "command": "npx",
  "args": [
    "-y",
    "@openephemeris/mcp-server"
  ],
  "env": {
    "OPENEPHEMERIS_PROFILE": "dev",
    "OPENEPHEMERIS_BACKEND_URL": "https://api.openephemeris.com",
    "OPENEPHEMERIS_API_KEY": "YOUR_API_KEY_HERE"
  }
}
```
<!-- GENERATED:CURSOR_INSTALL:END -->

### Manual install (stdio MCP clients)

```json
{
  "mcpServers": {
    "openephemeris": {
      "command": "npx",
      "args": ["-y", "@openephemeris/mcp-server"],
      "env": {
        "OPENEPHEMERIS_PROFILE": "dev",
        "OPENEPHEMERIS_BACKEND_URL": "https://api.openephemeris.com",
        "OPENEPHEMERIS_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}
```

### Platform guide

> **Detailed setup walkthroughs** for each platform are in [SETUP.md](./SETUP.md).

| Client | Install mode | Config location |
|---|---|---|
| Cursor | One-click deeplink or manual | `~/.cursor/mcp.json` |
| Claude Desktop (macOS) | Manual | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | Manual | `%APPDATA%\Claude\claude_desktop_config.json` |
| Windsurf | Manual | `~/.codeium/windsurf/mcp_config.json` (or legacy `~/.codeium/mcp_config.json`) |

### Client install walkthroughs

1. Cursor
   - Click the "Install in Cursor" button above, then replace `YOUR_API_KEY_HERE` in Cursor MCP settings.
   - If you prefer manual setup, paste the `mcpServers.openephemeris` block from "Manual install" into `~/.cursor/mcp.json`.
2. Claude Desktop (macOS/Windows)
   - Open the platform config file from the table above.
   - Add the same `mcpServers.openephemeris` block from "Manual install".
   - Restart Claude Desktop.
3. Windsurf
   - Open `~/.codeium/windsurf/mcp_config.json` (or the legacy `~/.codeium/mcp_config.json` path).
   - Add the `mcpServers.openephemeris` block from "Manual install".
   - Restart Windsurf.

### Remote-only clients (ChatGPT Developer Mode, Antigravity, etc.)

This package runs as a local stdio MCP server. Remote-only clients require a hosted MCP endpoint (Streamable HTTP/SSE), so you must run this server behind an MCP bridge/proxy and expose it over HTTPS before adding it in those clients.

### Auth and upgrade behavior in MCP clients

- 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`.
- Tier-gated endpoint (`403`): tool call returns an upgrade-required message with `https://openephemeris.com/pay` and dashboard billing/key management link.
- Monthly quota exhausted (`402`): tool call returns usage quota guidance with both dashboard (`/dashboard?tab=account`) and upgrade (`/pay`) links.
- Burst/rate limit (`429`): tool call returns retry guidance and links to dashboard usage monitoring.

## What You Can Ask

```
"Calculate a natal chart for 1990-04-15 at 2:30 PM in Chicago."
"Find all Saturn transits to my natal Sun in the next 6 months."
"Get the current moon phase and void-of-course status."
"Find the next solar eclipse visible from Tokyo."
"Find the best time to sign a contract in March — electional window."
"Generate a Human Design chart for my birth data."
"What is my Vedic (sidereal) chart?"
"Calculate my Chinese BaZi (Four Pillars) chart."
"Show me my Astrocartography power lines — where is my Venus line on the map?"
"Find all ACG lines within 3° of Paris for my chart."
"Calculate a synastry chart between two people."
"Find the next Venus Star Point and my relationship to it."
"What are the active planetary stations in the next 3 months?"
"Calculate primary directions for the next 5 years."
"Find my Firdaria time lord period."
"What is the sidereal time and delta-T right now?"
```

## Tools at a Glance

| Category | Tool | Tier |
|---|---|---|
| Natal chart | `ephemeris_natal_chart` | Explorer |
| Transit forecast | `ephemeris_transits` | Personal |
| Transit chart snapshot | `ephemeris_natal_transits` | Personal |
| Moon phase / VOC | `ephemeris_moon_phase` | Explorer |
| Eclipse next visible | `ephemeris_next_eclipse` | Explorer |
| Electional window | `ephemeris_electional` | Developer |
| Moment analysis | `electional_moment_analysis` | Developer |
| Station tracker | `electional_station_tracker` | Developer |
| Aspect search | `electional_aspect_search` | Developer |
| Human Design chart | `human_design_chart` | Explorer |
| HD composite | `human_design_composite` | Explorer |
| HD penta | `human_design_penta` | Explorer |
| HD return / opposition | `hd_planetary_return`, `hd_opposition` | Explorer |
| Vedic chart | `vedic_chart` | Explorer |
| BaZi (Chinese) | `chinese_bazi` | Explorer |
| Synastry | `ephemeris_synastry` | Developer |
| Composite chart | `ephemeris_composite` | Developer |
| Relocation chart | `ephemeris_relocation` | Developer |
| Progressed chart | `ephemeris_progressed_chart` | Explorer |
| Solar return | `ephemeris_solar_return` | Developer |
| Lunar return | `ephemeris_lunar_return` | Developer |
| Planetary return | `ephemeris_planetary_return` | Developer |
| Astrocartography lines | `acg_power_lines` | Developer |
| ACG hits at location | `acg_hits` | Scale |
| Venus Star Points | `venus_star_points` + 4 more | Explorer |
| Chart wheel image | `ephemeris_chart_wheel` | Developer |
| Bi-wheel image | `ephemeris_bi_wheel` | Developer |
| Dignities / Midpoints / Fixed stars | `ephemeris_dignities`, `ephemeris_midpoints`, `ephemeris_fixed_stars` | Explorer |

## Tooling Model

- Typed tools are preferred for common workflows (natal, transits, moon phase, eclipse, synastry, relocation, electional, Human Design).
- Generic tools: `dev.list_allowed` returns all currently allowlisted operations, and `dev.call` invokes any allowlisted operation by `method + path`.
- Security model: default-deny with explicit allowlist in `config/dev-allowlist.json`.
- Deny prefixes block sensitive route families (`/auth`, `/billing`, `/admin`, etc.).

### `dev.call` input

| Parameter | Type | Required | Description |
|---|---|---|---|
| `method` | `GET\|POST\|PUT\|PATCH\|DELETE` | Yes | HTTP method |
| `path` | `string` | Yes | Absolute API path, e.g. `/ephemeris/natal-chart` |
| `query` | `object` | No | Query parameters |
| `body` | `object` | No | JSON body for non-GET requests |
| `preset` | `full\|simple` | No | Convenience mapping to `query.preset` |
| `format` | `json\|llm\|llm_v2` | No | Convenience mapping to `query.format` (`llm_v2` normalizes to `llm`) |
| `output_mode` | `full\|simple\|llm\|llm_v2` | No | Legacy compatibility field |

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `OPENEPHEMERIS_API_KEY` | Yes (unless service key/JWT used) | API key for OpenEphemeris |
| `ASTROMCP_API_KEY` | No | Legacy alias for `OPENEPHEMERIS_API_KEY` (checked as fallback) |
| `OPENEPHEMERIS_BACKEND_URL` | No | Defaults to `https://api.openephemeris.com` |
| `OPENEPHEMERIS_PROFILE` | No | `dev` by default |
| `OPENEPHEMERIS_SERVICE_KEY` | No | Internal service auth |
| `OPENEPHEMERIS_JWT` | No | Bearer token auth |
| `OPENEPHEMERIS_DEV_ALLOWLIST_PATH` | No | Override allowlist file path |
| `MCP_USER_ID` | No | Per-instance user identifier |

Legacy aliases (`ASTROMCP_*`, `MERIDIAN_*`) remain supported.

## Legal

This 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).

## Development

```bash
npm install
npm run dev
npm run typecheck
npm test
npm run regen:dev-allowlist
npm run check:dev-allowlist
npm run sync:readme
npm run check:readme
npm run verify:release
```

### Deploying the SSE Server to Fly.io

When you update the MCP server logic (handlers, bug fixes, hardening), you should deploy it so clients connecting via our remote `https://mcp.openephemeris.com/sse` endpoint get the updates immediately.

1. Navigate to `apps/api/mcp-server`
2. Run `fly deploy --remote-only`

*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.

`npm run verify:release` is the release gate. It checks:
- allowlist freshness against OpenAPI
- schema pack freshness
- README synchronization
- type safety + tests
- publish tarball contents (`npm pack --dry-run --json`)

## Architecture

```text
MCP Client (Cursor / Claude / Windsurf / other stdio clients)
    | stdio JSON-RPC
    v
openephemeris-mcp (Node.js)
    | typed tools + dev.call/dev.list_allowed
    | auth chain: Service Key > API Key > JWT
    v
OpenEphemeris API
```

<!-- GENERATED:RUNTIME_SNAPSHOT:BEGIN -->
## Runtime Snapshot (Generated)

Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live tool registry.

- Allowlisted operations: **22**
- Methods: `GET=4`, `POST=18`, `PUT=0`, `PATCH=0`, `DELETE=0`
- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **48**
- Typed tools: `auth_login`, `auth_logout`, `auth_status`, `chinese_bazi`, `dev_call`, `dev_list_allowed`, `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_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `hd_opposition`, `hd_planetary_return`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
- Generic tools: 

### Allowlist Families

| Family | Operations | Example |
|---|---:|---|
| `acg` | 4 | `POST /acg/ccg`, `POST /acg/hits` |
| `comparative` | 5 | `POST /comparative/composite`, `POST /comparative/composite/midpoint` |
| `electional` | 4 | `GET /electional/aspect-search`, `GET /electional/find-window` |
| `ephemeris` | 1 | `POST /ephemeris/relocation` |
| `predictive` | 6 | `POST /predictive/returns`, `POST /predictive/returns/lunar` |
| `visualization` | 2 | `POST /visualization/bi-wheel`, `POST /visualization/chart-wheel` |
<!-- GENERATED:RUNTIME_SNAPSHOT:END -->

## Why OpenEphemeris for AI Agents?

Most LLMs (like Claude and ChatGPT) struggle heavily with astronomical calculations (trigonometry, Julian date conversions, and Swiss Ephemeris lookups). OpenEphemeris serves as a **secure, remote math engine**.

By pairing LLMs with the OpenEphemeris MCP server, your agents can instantly access:
- **Zero-hallucination coordinates**: Direct, sub-arcsecond NASA JPL DE440/DE441 calculations.
- **LLM-optimized tokens (`format=llm`)**: We compress standard 25,000 token JSON chart responses into minimal text blocks, cutting your inference costs by 50%.
- **Ready-to-use astrology layers**: Built-in support for Astrocartography geoJSON lines, Hermetic Lots, Fixed Stars, and complex Human Design matrix generation.