openephemeris/openephemeris-MCP

**Use it in Claude:** add https://mcp.openephemeris.com/mcp as a custom connector (leave the OAuth Client ID and Secret blank) or install the Open Ephemeris plugin from the Claude directory. Sign-in happens in the browser and creates a free account with 150 credits.
Model 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.
**Hosted endpoint:** https://mcp.openephemeris.com/mcp (Streamable HTTP, MCP 2025-11-25 spec)
Quick Start
Install via Smithery (recommended)
The fastest way to connect any MCP-compatible client:
Or browse the listing and copy connection snippets: **smithery.ai/servers/open-ephemeris/openephemeris**
---
Connect via AI SDK (Vercel AI SDK)
Connect via MCP SDK (TypeScript)
Connect directly (Streamable HTTP, no Smithery)
---
One-click install (Cursor)
> Replace YOUR_API_KEY_HERE in Cursor MCP settings with your API key from https://openephemeris.com/dashboard.
Cursor deeplink payload:
Manual install (stdio MCP clients)
Platform guide
> **Detailed setup walkthroughs** for each platform are in SETUP.md.
| Client | Install mode | Config location |
|---|---|---|
| Smithery | One-click | smithery.ai |
| 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) |
| ChatGPT | One-click | Open Ephemeris in the ChatGPT app directory |
| Claude Web / remote clients | Hosted URL | https://mcp.openephemeris.com/mcp |
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 (Claude Web, ChatGPT, etc.)
The 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:
- **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.
- **ChatGPT**: Open Ephemeris is an approved app in the ChatGPT app directory. Open
the listing, click **Install plugin**, approve the sign-in (that also creates your
free OpenEphemeris account), then type @Open Ephemeris in any chat. Charts render inline,
exactly as they do in Claude. Prefer to wire it yourself? **Settings → Plugins → Advanced →
Developer mode → + Create app** accepts https://mcp.openephemeris.com/mcp with
Authentication on **OAuth** — no client ID or secret to enter.
- **Via Smithery**: Use the Smithery listing for managed connections with any client
- **Legacy SSE**: retired in 3.20.0 — use Streamable HTTP at /mcp
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.
- Out of credits (402): tool call returns a one-tap top-up link (Explorer's 150 free credits are one-time and do not reset; plan allowances renew each billing period) plus the dashboard usage link. Failed calls (any 4xx/5xx) are refunded.
- Burst/rate limit (429): tool call returns retry guidance and links to dashboard usage monitoring.