Skip to main content
Glama
Precision astronomical ephemeris and planetary positions via the Swiss Ephemeris.

Precision astronomical ephemeris and planetary positions via the Swiss Ephemeris.

Ephemeris MCP 🌌

PyPI version CI License: AGPL v3

mcp-name: io.github.scottchronicity/ephemeris-mcp

Precision Astronomical Ephemeris for AI Agents.

Ephemeris MCP is a Model Context Protocol (MCP) server that provides AI agents with precision planetary positions using the Swiss Ephemeris.

To use this in Claude Desktop, add this to your claude_desktop_config.json:

"mcpServers": {
  "ephemeris": {
    "command": "uvx",
    "args": ["ephemeris-mcp"]
  }
}

Quick Start

# Install with uvx (recommended - fast & isolated, no local install needed)
uvx ephemeris-mcp

# Or install globally with pip
pip install ephemeris-mcp
python -m ephemeris_mcp

Register with MCP Clients

Add to your MCP client configuration (client will start server on-demand):

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ephemeris-mcp": {
      "command": "uvx",
      "args": ["ephemeris-mcp"]
    }
  }
}

VS Code/Cursor/Windsurf (Cline MCP settings):

{
  "mcpServers": {
    "ephemeris-mcp": {
      "command": "uvx",
      "args": ["ephemeris-mcp"]
    }
  }
}

The client starts the server process automatically, communicates over stdin/stdout, then terminates it when done.

Related MCP server: AstroConsultant

Alternative: Docker

If you prefer container isolation:

# Pull latest image
docker pull ghcr.io/scottchronicity/ephemeris-mcp:latest

# Test it
docker run --rm -i ghcr.io/scottchronicity/ephemeris-mcp:latest

Configure MCP client with Docker:

{
  "mcpServers": {
    "ephemeris-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/scottchronicity/ephemeris-mcp:latest"]
    }
  }
}

Local Development

# Clone and install
git clone https://github.com/scottchronicity/ephemeris-mcp.git
cd ephemeris-mcp
uv sync

# Run tests
make test

# Run locally
uv run ephemeris-mcp

# Test the engine directly
make validate-happycase

Available Tools

get_planetary_positions

Returns precise Tropical Zodiac positions for all planets, Sun, Moon, and chart angles.

Parameters:

  • iso_time (string): ISO-8601 timestamp (e.g., "2025-12-16T15:28:00Z")

  • latitude (float): Observer latitude (default: 42.3314 - Detroit, MI)

  • longitude (float): Observer longitude (default: -83.0458 - Detroit, MI)

Returns:

  • bodies: Sun, Moon, planets with sign, degrees, motion (direct/retrograde), speed, declination

  • houses: Ascendant (ASC) and Midheaven (MC) with sign and degrees

Architecture

See docs/adr/ for architectural decisions:

  • ADR 001: Geocentric Tropical Ecliptic coordinates specification

  • ADR 002: Semantic versioning with Conventional Commits

  • ADR 003: CI/CD pipeline architecture

License

AGPLv3

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    • Swiss Ephemeris for AI agents: exact natal charts, transits, synastry and birth-place resolution

    • Professional Vedic astrology tools for AI agents via MCP.

      https://mcp.vedavisor.com/mcp
    • AstroMansion is a hosted MCP server for astrology computed exactly, never estimated. Positions come from our own engine on NASA JPL ephemerides, with no third-party astrology API behind it. Checked against NASA JPL Horizons, major-planet positions stay within half an arcsecond, and the audit is public at https://astromansion.com/en/accuracy. 52 techniques Natal charts, transits and transit hits, stations, solar, lunar and Saturn returns, secondary progressions, solar arc, primary directions, synastry, composite charts, compatibility, dignities, profections, firdaria, zodiacal releasing, decennials, horary, electional, lunar mansions, Arabic lots, Vedic charts, nakshatras, Vimshottari dasha, navamsa, aspect patterns, midpoints, antiscia, declinations, harmonics, draconic and heliocentric charts, astrocartography, fixed stars, parans, heliacal risings, rectification, great conjunctions, Venus star points, ingresses, the age point, temperament and moon phases. Tools - search_places finds a birthplace with its coordinates and time zone. - natal_chart casts a birth chart with its planets, houses and aspects. - body_sign tells the sign a body stood in at a birth. - list_techniques lists every technique, the plan it needs, and an example of its options. - run_technique runs any of the 52 techniques. - sky_calendar lists moon phases, retrogrades, eclipses and void-of-course Moon periods. - chart_image draws the chart wheel as a PNG. - mansionsql_query answers SQL questions about a chart. Eight tools keep the assistant's context small. list_techniques shows what exists, and run_technique runs it. Connect - Claude and ChatGPT: add https://api.astromansion.com/mcp as a custom connector and sign in with your AstroMansion account. - Claude Code: claude mcp add --transport http astromansion https://api.astromansion.com/mcp --header "X-API-Key: YOUR_KEY" - Any other client: Streamable HTTP at https://api.astromansion.com/mcp, with OAuth or an X-API-Key header. Plans The free plan includes 100 calls a month for natal charts. Paid plans open the other techniques. See https://astromansion.com/en/pricing.

      https://api.astromansion.com/mcp
    • Official Divine API MCP for Western Astrology: Natal, Synastry, Transit, Composite, Progressions.

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Astrology MCP server that computes natal charts, transits, synastry, progressions, returns, eclipses, retrogrades, and moon phases from a real ephemeris, enabling AI agents to provide accurate astrological calculations without hallucination.
      12
      75 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An AI astrology MCP server providing 49 tools for Western and Vedic astrology calculations, including natal charts, dashas, transits, and compatibility analysis, powered by Swiss Ephemeris.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A Vedic astrology MCP server that computes birth charts, dashas, transits, and yogas locally using Swiss Ephemeris, enabling an LLM to interpret horoscopes and provide personalized advice.
      -
    • F
      license
      Not graded
      quality
      B
      maintenance
      MCP server for astrological calculations including natal charts, planetary positions, aspects, transits, and progressions using Swiss Ephemeris.
      -