@morphemeris/mcp

MCP (Model Context Protocol) server for the Morphemeris astronomical ephemeris API. Gives AI coding agents direct access to planetary positions, house cusps, fixed stars, and other astronomical calculations.

Prerequisites

You'll need a Morphemeris API key. Sign up at morphemeris.com and create a key at morphemeris.com/dashboard/keys. The free tier includes 500 requests/month.

For this package you'll also need Node.js 20 or later. The hosted server below needs no runtime at all.

Hosted server — no install

There's a hosted endpoint with the same 33 tools:

claude mcp add --transport http morphemeris https://mcp.morphemeris.com \
  --header "Authorization: Bearer morphemeris_live_YOUR_KEY_HERE"

or, in a JSON config:

{
  "mcpServers": {
    "morphemeris": {
      "type": "http",
      "url": "https://mcp.morphemeris.com",
      "headers": { "Authorization": "Bearer morphemeris_live_YOUR_KEY_HERE" }
    }
  }
}

Same tools, same pricing, nothing to install or keep updated. Use this package instead when you want to work offline, pin a specific version, or your client doesn't support remote MCP servers.

Protocol support

Version 0.7.0 and later implement MCP revision 2026-07-28, which is stateless — there's no connection handshake and no session to keep alive, so the server does no work between your requests.

Clients that still speak the earlier initialize-based revisions are served too, so you don't need to check what revision your agent supports before upgrading.

Installation

Claude Code

Claude Code MCP docs

From your terminal (not inside Claude Code):

claude mcp add morphemeris \
  -e MORPHEMERIS_API_KEY=morphemeris_live_... \
  -- npx -y @morphemeris/mcp

You can control where the server is available with the -s (scope) flag:

• local (default) — only you, only in the current project directory
• project — saved to .mcp.json in the project root, shared with your team via version control (requires approval on first use)
• user — available across all your projects on this machine

For example, to make Morphemeris available everywhere: claude mcp add morphemeris -s user ...

After adding, start a new Claude Code conversation and run /mcp to verify the server appears. If it shows as disabled, select it and enable it. You may need to enable it a second time on first setup — this is a known quirk with newly added MCP servers.

Cursor

Cursor MCP docs

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "morphemeris": {
      "command": "npx",
      "args": ["-y", "@morphemeris/mcp"],
      "env": {
        "MORPHEMERIS_API_KEY": "morphemeris_live_..."
      }
    }
  }
}

VS Code (GitHub Copilot)

VS Code MCP docs

Add to .vscode/mcp.json in your project root, or use the command palette: MCP: Open User Configuration for global setup.

{
  "servers": {
    "morphemeris": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@morphemeris/mcp"],
      "env": {
        "MORPHEMERIS_API_KEY": "morphemeris_live_..."
      }
    }
  }
}

MCP tools are only available in Copilot's Agent mode — select "Agent" from the mode dropdown in Copilot Chat.

Windsurf

Windsurf MCP docs

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "morphemeris": {
      "command": "npx",
      "args": ["-y", "@morphemeris/mcp"],
      "env": {
        "MORPHEMERIS_API_KEY": "morphemeris_live_..."
      }
    }
  }
}

OpenAI Codex CLI

Codex MCP docs

Add to ~/.codex/config.toml (global) or .codex/config.toml (project):

[mcp_servers.morphemeris]
command = "npx"
args = ["-y", "@morphemeris/mcp"]

[mcp_servers.morphemeris.env]
MORPHEMERIS_API_KEY = "morphemeris_live_..."

Gemini CLI

Gemini CLI MCP docs

Add to ~/.gemini/settings.json (global) or .gemini/settings.json (project):

{
  "mcpServers": {
    "morphemeris": {
      "command": "npx",
      "args": ["-y", "@morphemeris/mcp"],
      "env": {
        "MORPHEMERIS_API_KEY": "morphemeris_live_..."
      }
    }
  }
}

Configuration

| Variable | Required | Description | |----------|----------|-------------| | MORPHEMERIS_API_KEY | Yes | Your API key from morphemeris.com/dashboard/keys | | MORPHEMERIS_API_URL | No | API base URL (default: https://api.morphemeris.com) |

Tools

| Tool | Description | |------|-------------| | calculate_positions | Planetary positions (longitude, latitude, distance, speed) | | calculate_houses | House cusps and angles (Ascendant, MC) for 23 systems | | calculate_chart | Full chart: positions + houses in one call | | get_fixed_stars | Fixed star positions and magnitudes | | get_ayanamsha | Ayanamsha for all 47 sidereal systems | | get_delta_t | Delta T (TT - UT) for time scale conversion | | get_sidereal_time | Greenwich and Local Sidereal Time | | find_solar_eclipses | Find upcoming or past solar eclipses with optional local data | | find_lunar_eclipses | Find upcoming or past lunar eclipses with optional visibility | | find_heliacal_event | Heliacal rising/setting of planets (first/last visibility) | | find_ingresses | Find when a planet crosses into a zodiac sign | | find_transits | Aspect windows over a date range: transits to a natal chart, or the moving bodies against each other | | batch_requests | Send up to 50 sub-requests in a single API call | | natal_chart | Full natal chart with aspects, parallels, dignities, OOB detection | | calculate_patterns | Aspect patterns (T-square, grand trine, yod, kite, grand cross, mystic rectangle, stellium) with the aspects they're built from | | calculate_astrocartography | Astrocartography lines: MC/IC/ASC/DSC and any house cusp, as polylines with termination reasons | | calculate_midpoints | Midpoints of every pair, antiscia, lots, and midpoint trees on a dial | | calculate_aspects | Aspects and parallels between bodies at a given time | | calculate_dignities | Essential dignities, scores, and dispositorship chains | | calculate_synastry | Two-chart synastry with inter-chart aspects | | calculate_composite | Midpoint composite chart from two charts | | calculate_davison | Davison relationship chart (time-space midpoint) | | calculate_progressed | Secondary progressed chart (day-for-a-year) | | calculate_draconic | Draconic chart (North Node = 0° Aries rotation) | | find_returns | Planetary return charts (Sun, Moon, or other body returning to natal longitude) | | calculate_lots | The seven Hermetic lots (Fortune, Spirit, Eros, Necessity, Courage, Victory, Nemesis) with day/night reversal | | calculate_solar_proximity | Solar proximity: cazimi, combust, under the beams, or free | | calculate_void_of_course | Void-of-course Moon analysis | | calculate_planetary_hours | 24 planetary hours in Chaldean order | | calculate_profections | Annual and monthly profections: the lord of the year and month, at one instant or over a range, with mean-year or solar-return boundaries | | calculate_firdaria | Firdaria: the Persian 75-year sequence of major periods and sub-periods by sect | | calculate_zodiacal_releasing | Zodiacal releasing from a lot at up to four levels, with lords, angularity to Fortune, and the loosing of the bond | | list_available_values | Discover valid bodies, house systems, ayanamsha systems, eclipse types, heliacal events, zodiac signs |

Examples

Ask your AI agent:

• "Calculate a natal chart for June 15, 1990 at 2:30 PM in Harrisonburg, VA"
• "What are the current planetary positions?"
• "Show me the fixed star Aldebaran's position today"
• "When is the next solar eclipse visible from New York?"
• "Find the next 5 Sun ingresses into Aries"
• "Get positions for Sun and Moon every day this week" (uses batch)
• "What aspects does my chart have?" (uses natal_chart or calculate_aspects)
• "Compare my chart with my partner's" (uses synastry)
• "What are my current secondary progressions?" (uses progressed)
• "Calculate my 2025 solar return for Harrisonburg, VA" (uses find_returns)
• "What's my Part of Fortune?" (uses calculate_lots)
• "Is Mercury combust right now?" (uses calculate_solar_proximity)
• "Is the Moon void of course?" (uses calculate_void_of_course)
• "What planetary hour is it in New York?" (uses calculate_planetary_hours)
• "Who is my lord of the year right now?" (uses calculate_profections)
• "What firdaria period am I in?" (uses calculate_firdaria)
• "When does my next zodiacal releasing peak period begin?" (uses calculate_zodiacal_releasing)

A note about time zones

The Morphemeris API expects all datetimes in UTC. When you ask your agent about a specific local time (e.g., "7:30 PM Eastern"), the agent will convert it to UTC before calling the API. This conversion is usually correct, but be aware of edge cases involving historical daylight saving time changes.

For example, in the United States, the Emergency Daylight Saving Time Energy Conservation Act of 1973 moved the start of DST to January 6, 1974 due to the oil crisis — so February 1974 was EDT (UTC-4), not the EST (UTC-5) that most models assume. If precision matters, provide the UTC time directly or verify the agent's conversion, especially for dates before 2000 or in regions with unusual DST history.

Pricing

Morphemeris offers a free tier of 500 requests/month. Additional requests are $0.01 each via prepaid credits. Get your API key at morphemeris.com.

License

MIT