{
  "markdown": "# Ephemeris MCP 🌌\n\n[![PyPI version](https://badge.fury.io/py/ephemeris-mcp.svg)](https://badge.fury.io/py/ephemeris-mcp)\n[![CI](https://github.com/scottchronicity/ephemeris-mcp/actions/workflows/ci-pr.yml/badge.svg)](https://github.com/scottchronicity/ephemeris-mcp/actions/workflows/ci-pr.yml)\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n\nmcp-name: io.github.scottchronicity/ephemeris-mcp\n\n**Precision Astronomical Ephemeris for AI Agents.**\n\nEphemeris MCP is a Model Context Protocol (MCP) server that provides AI agents with precision planetary positions using the **Swiss Ephemeris**.\n\nTo use this in Claude Desktop, add this to your `claude_desktop_config.json`:\n\n```json\n\"mcpServers\": {\n  \"ephemeris\": {\n    \"command\": \"uvx\",\n    \"args\": [\"ephemeris-mcp\"]\n  }\n}\n```\n\n## Quick Start\n\n### Install via PyPI (Recommended)\n\n```bash\n# Install with uvx (recommended - fast & isolated, no local install needed)\nuvx ephemeris-mcp\n\n# Or install globally with pip\npip install ephemeris-mcp\npython -m ephemeris_mcp\n```\n\n### Register with MCP Clients\n\nAdd to your MCP client configuration (client will start server on-demand):\n\n**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"ephemeris-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"ephemeris-mcp\"]\n    }\n  }\n}\n```\n\n**VS Code/Cursor/Windsurf** (Cline MCP settings):\n\n```json\n{\n  \"mcpServers\": {\n    \"ephemeris-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"ephemeris-mcp\"]\n    }\n  }\n}\n```\n\nThe client starts the server process automatically, communicates over stdin/stdout, then terminates it when done.\n\n## Alternative: Docker\n\nIf you prefer container isolation:\n\n```bash\n# Pull latest image\ndocker pull ghcr.io/scottchronicity/ephemeris-mcp:latest\n\n# Test it\ndocker run --rm -i ghcr.io/scottchronicity/ephemeris-mcp:latest\n```\n\nConfigure MCP client with Docker:\n\n```json\n{\n  \"mcpServers\": {\n    \"ephemeris-mcp\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"--rm\", \"-i\", \"ghcr.io/scottchronicity/ephemeris-mcp:latest\"]\n    }\n  }\n}\n```\n\n## Local Development\n\n```bash\n# Clone and install\ngit clone https://github.com/scottchronicity/ephemeris-mcp.git\ncd ephemeris-mcp\nuv sync\n\n# Run tests\nmake test\n\n# Run locally\nuv run ephemeris-mcp\n\n# Test the engine directly\nmake validate-happycase\n```\n\n## Available Tools\n\n### `get_planetary_positions`\n\nReturns precise Tropical Zodiac positions for all planets, Sun, Moon, and chart angles.\n\n**Parameters:**\n\n- `iso_time` (string): ISO-8601 timestamp (e.g., `\"2025-12-16T15:28:00Z\"`)\n- `latitude` (float): Observer latitude (default: 42.3314 - Detroit, MI)\n- `longitude` (float): Observer longitude (default: -83.0458 - Detroit, MI)\n\n**Returns:**\n\n- `bodies`: Sun, Moon, planets with sign, degrees, motion (direct/retrograde), speed, declination\n- `houses`: Ascendant (ASC) and Midheaven (MC) with sign and degrees\n\n## Architecture\n\nSee [docs/adr/](docs/adr/) for architectural decisions:\n\n- **ADR 001**: Geocentric Tropical Ecliptic coordinates specification\n- **ADR 002**: Semantic versioning with Conventional Commits\n- **ADR 003**: CI/CD pipeline architecture\n\n## License\n\nAGPLv3\n",
  "bytes": 3222,
  "sha": "f48622baea67597d83ae1ceac679a3b9e4b3de512dee1bbe4e7a7a1898154fe9",
  "repo_slug": "scottchronicity/ephemeris-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_scottchronicity_ephemeris_mcp_6a2bce87/readme"
}