Horosa Skill

What Horosa Skill MCP server does

Horosa Skill MCP server turns the existing Horosa (星阙) calculation stack into interfaces that AI clients can call locally. It covers 110 techniques across Western astrology, Chinese metaphysics, divination, calendrical methods, and 14 routes of shenshu. The repository presents the service as both an MCP server and a JSON-first command-line application.

The calculations are performed on the local machine rather than uploaded to a remote service. The implementation uses Horosa-related local algorithms, ephemeris data, Java and Python runtime components, a headless JavaScript layer, and local storage. Its stated goal is to preserve the same underlying results and export structure used by the Horosa desktop application.

How it works

Start the local service with the CLI, then connect an MCP-capable client over stdio or streamable HTTP. The default HTTP endpoint shown in the documentation is http://127.0.0.1:8765/mcp. A JSON-first CLI is also available for scripts and workflows that do not use MCP.

Each invocation returns a shared response envelope. Techniques that support the export contract can provide an export_snapshot, while the complete snapshot is archived locally. A clarification gate blocks calculations when important inputs such as time, location, timezone, gender, subject, house system, calendar, or setup method still need confirmation. The response can include a technique evidence card describing the method, school or convention, calculation source, completeness, and version chain.

horosa_hecan supports parallel calculations and comparison across techniques. The documented comparison format separates agreement from disagreement instead of concealing differences. horosa_technique_report produces a method-focused report, and session-level checks can identify conflicts between technique conventions.

Setup and configuration

The documented source installation requires uv, Python 3.12 or later managed by uv, and roughly 5 GB of available disk space. The usual sequence is to clone the repository, run uv sync, install the offline runtime, run doctor and selfcheck, then start the service. Release wheels can also be launched with uvx without cloning the repository.

The runtime download supports mirrors and resumable installation. HOROSA_RUNTIME_MIRROR changes the download source. HOROSA_RUNTIME_ROOT can place the runtime in a shorter or ASCII-only path, which is particularly relevant on Windows. The documentation also describes experimental Docker and Linux gateway use, but the offline runtime payloads are published for macOS arm64 and Windows x64; a gateway must point to a runtime hosted elsewhere.

Tools and capabilities

The Horosa Skill MCP server provides:

• 110 technique tools spanning the documented astrology and metaphysics categories.
• Local calculation with offline operation after runtime installation.
• Evidence cards and structured export snapshots for supported techniques.
• SQLite full-text search and JSON artifact archival for previous calls.
• DOCX, PDF, JSON, and report-generation workflows.
• Multi-technique comparison through horosa_hecan.
• Method reports through horosa_technique_report.
• Response views that can request section titles or selected sections.

Limitations and notes

The runtime is not a general Linux-native offline package according to the provided material. If the Java backend is unavailable, the system can fall back to chart-only operation, leaving some calendrical and related methods unavailable. Windows installations may require an ASCII runtime path, and macOS may require removing quarantine attributes from downloaded runtime binaries.

The repository states that the PyPI channel is not yet enabled, so the documented zero-install route uses a release wheel URL. Docker support is described as experimental. The project is licensed under AGPL-3.0, and its outputs should be interpreted according to the selected technique and convention rather than treated as a single universal method.