# ephemeris-mcp [Health: Active]

**Category:** 🚀 Aerospace & Astrodynamics  
**Repository:** https://github.com/scottchronicity/ephemeris-mcp  
**GitHub Stars:** 4  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ephemeris-mcp

## Description
Precision astronomical ephemeris and planetary positions via the Swiss Ephemeris.

## Tools
Capabilities this server exposes over MCP:

- **get_planetary_positions** — Returns precise Tropical Zodiac positions for all planets, Sun, Moon, and chart angles.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

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

## Documentation

## What ephemeris-mcp MCP server does

ephemeris-mcp MCP server exposes Swiss Ephemeris calculations to MCP-compatible AI clients. It focuses on position data rather than general astronomy workflows: one available tool calculates Tropical Zodiac placements for the Sun, Moon, planets, and chart angles.

The result includes a `bodies` collection with each body's sign, degree, apparent motion direction, speed, and declination. A separate `houses` collection reports the Ascendant (ASC) and Midheaven (MC), including their signs and degrees. This makes the server suitable for agents that need to retrieve chart-related positions from a timestamp and observing location.

## How it works

Call `get_planetary_positions` with an ISO-8601 timestamp such as `2025-12-16T15:28:00Z`. Supply the observer's latitude and longitude as floating-point values when the calculation should use a location other than the defaults. The documented defaults are 42.3314 latitude and -83.0458 longitude, corresponding to Detroit, Michigan.

The MCP client starts the server as a subprocess and exchanges messages over standard input and output. Once the client no longer needs the process, it can terminate it. The calculation engine uses the Swiss Ephemeris, while the returned coordinate system is geocentric Tropical Ecliptic according to the project's architecture notes.

## Setup and configuration

The recommended package-based setup runs the server with `uvx`, which avoids a separate local installation:

```bash
uvx ephemeris-mcp
```

A global pip installation is also documented:

```bash
pip install ephemeris-mcp
python -m ephemeris_mcp
```

Register the executable in the MCP client's server configuration with `uvx` as the command and `ephemeris-mcp` as its argument. Docker is an alternative when container isolation is preferred. The published image is `ghcr.io/scottchronicity/ephemeris-mcp:latest`; the documented client configuration runs it with `docker run --rm -i`.

For development, the repository uses `uv sync`, `uv run ephemeris-mcp`, and a Makefile for tests and validation. No environment variables are specified in the available setup instructions.

## Tools and capabilities

The server currently documents one tool:

- `get_planetary_positions`: Calculates Tropical Zodiac positions for the Sun, Moon, planets, and chart angles from an ISO-8601 time and observer coordinates.

Its response provides body-level sign, degree, motion, speed, and declination fields, plus Ascendant and Midheaven data. ephemeris-mcp MCP server therefore fits requests that need structured position output, rather than a broad collection of ephemeris queries or mutation operations.

## Limitations and notes

Latitude and longitude affect the location-dependent chart angles, and omitted coordinates fall back to the documented Detroit defaults. The project is licensed under AGPLv3, so review that license before embedding or distributing the server in a larger application.

_Full upstream README: https://allmcps.com/mcp/ephemeris-mcp/readme_