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

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 21 systems | | calculate_chart | Full chart: positions + houses in one call | | get_fixed_stars | Fixed star positions and magnitudes | | get_ayanamsha | Precession offset for 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 | | 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_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 | Arabic Parts/Lots (7 Hermetic lots 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 | | 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)

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