Metadata-Version: 2.4
Name: ephemeris-mcp
Version: 1.2.0
Summary: Precision astronomical ephemeris calculations via Model Context Protocol (MCP). Provides planetary positions using Swiss Ephemeris.
Project-URL: Homepage, https://github.com/scottchronicity/ephemeris-mcp
Project-URL: Documentation, https://github.com/scottchronicity/ephemeris-mcp#readme
Project-URL: Repository, https://github.com/scottchronicity/ephemeris-mcp
Project-URL: Issues, https://github.com/scottchronicity/ephemeris-mcp/issues
Author-email: Scott Carroll <scott@rippleroot.studios>
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: ai,astrology,ephemeris,llm,mcp,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.12,>=3.10
Requires-Dist: flatlib
Requires-Dist: mcp>=0.1.0
Requires-Dist: pydantic
Requires-Dist: structlog>=24.0.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: python-semantic-release>=9.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Ephemeris MCP 🌌

[![PyPI version](https://badge.fury.io/py/ephemeris-mcp.svg)](https://badge.fury.io/py/ephemeris-mcp)
[![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)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)

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`:

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

## Quick Start

### Install via PyPI (Recommended)

```bash
# 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`):

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

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

```json
{
  "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:

```bash
# 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:

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

## Local Development

```bash
# 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/](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
