Summary
Wraps the Swiss Ephemeris library to give AI agents precision planetary positions in tropical zodiac coordinates. Exposes a single tool, get_planetary_positions, that takes an ISO timestamp and lat/long coordinates and returns geocentric positions for the Sun, Moon, planets, plus chart angles like Ascendant and Midheaven. Each body comes back with zodiac sign, degrees, retrograde status, speed, and declination. Reach for this when you're building astrological chart tools, need accurate historical or future planetary data, or want to answer astronomical position queries without maintaining ephemeris files yourself. Ships as a PyPI package that runs via uvx or as a Docker container.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Ephemeris MCP 🌌
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, declinationhouses: 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
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →