mcpField
E
ephemeris-mcp

ephemeris-mcp

Local
github.com/scottchronicityScience & Education4Updated 31w ago
Repository

About ephemeris-mcp

ephemeris-mcp is an MCP server for AI agents and applications that need astronomical positions. Using Swiss Ephemeris, it returns Tropical Zodiac positions and chart angles for a specified time and location.

Key features

  1. 01Swiss Ephemeris calculations
  2. 02Planetary positions for a given time
  3. 03Latitude and longitude inputs
  4. 04Tropical Zodiac signs and degrees
  5. 05Ascendant and Midheaven angles

Use cases

  1. 01Retrieve planetary positions for a timestamp
  2. 02Calculate chart angles for a location
  3. 03Supply astronomical data to an AI agent

MCP support

It exposes the `get_planetary_positions` tool to MCP clients, returning bodies and house angles for the requested time and coordinates.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "scottchronicity-ephemeris": {
      "command": "uvx",
      "args": [
        "ephemeris-mcp"
      ]
    }
  }
}
Run commanduvx ephemeris-mcp

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
pypiephemeris-mcp1.2.0

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

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 via PyPI (Recommended)
# 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.

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

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.