Caelus MCP

What caelus-mcp does

The caelus-mcp MCP server exposes Caelus astrology calculations to MCP-compatible clients. The surrounding Caelus project is a clean-room astrology computation monorepo written around a TypeScript engine. Its documented scope includes ephemeris positions, charts, events, Hellenistic timing techniques, Vedic methods, citable chart facts, and sky-view image-prompt frames.

The MCP package is specifically described as providing tools for charts, transits, synastry, events, and eclipses. The current listing also identifies nine chart tools covering positions, houses, aspects, transits, and electional calculations. This makes the package relevant for agents that need computed astrological data rather than a general-purpose text or horoscope service.

Caelus is stated to contain no Swiss Ephemeris code, no AGPL code, and no ephemeris files. The repository describes its engine as having zero runtime dependencies and approximately 153 KB of gzipped TypeScript output in total. Those properties apply to the Caelus engine package in the monorepo and provide context for the MCP package's computational basis.

Tools and capabilities

The documented capabilities include:

• Computing ephemeris positions.
• Producing chart data.
• Working with houses and aspects.
• Examining transits.
• Comparing charts through synastry.
• Handling astrological events and eclipses.
• Supporting electional calculations.
• Exposing the broader Caelus chart and timing methods through MCP tooling.

Developers should consult the repository's MCP tool contract for those implementation details before building a client integration.

How it works

The caelus-mcp MCP server sits alongside the caelus TypeScript engine in the repository's package layout. The repository also includes a birth package for converting birth time and place into UT, a wheel package for rendering React SVG chart wheels, and a web application with a chart API; these are separate packages rather than documented MCP client requirements.

The project links to ephemengine.com as its live site. The repository's web application can serve a browser playground and an edge endpoint using requests such as /api/chart?date=…&lat=…&lon=…, but that endpoint should not be assumed to be the MCP transport or API without checking the package documentation.

Setup and configuration

The repository quick start uses Node package commands:

npm install
npm run build
npm test
npm run dev -w web

The last command starts the web application, which the README places at http://localhost:3000. Use the repository's MCP_SPEC.md and package documentation to determine how to start and configure the MCP server itself.

The project identifies main as the stable-release branch and dev as the active-development branch. The package table lists packages/caelus-mcp as the MCP package and links it to the caelus-mcp npm package.

Limitations and notes

It also does not establish that the browser chart endpoint can substitute for MCP access. The clean-room implementation and absence of ephemeris files are explicit project properties, but precision, supported date ranges, coordinate rules, and compatibility with other astrology engines are not specified here.

The repository is licensed MIT according to its top-level description. The package list distinguishes the runtime TypeScript engine from the Python reference and fitting code, so deployment planning should treat those components separately.