# Horosa Skill

> Horosa Skill is an open-source MCP server for astrology. Offline server with 114 Chinese metaphysics and Western astrology chart techniques. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** macOS, Windows, Linux, CLI, self-hosted
- **Repository:** https://github.com/horace-maxwell/horosa-skill
- **MCP Registry name:** io.github.Horace-Maxwell/horosa-skill
- **Categories:** [astrology](https://ai-powered.com/categories/astrology)
- **Listing updated:** 2026-11-18

## About

Horosa Skill packages the calculation methods of the Horosa (星阙) desktop app as an MCP server and a JSON-first command line, with all computation done locally. The README lists Western natal, progression, horary and electional work, plus Bazi, Zi Wei Dou Shu, Da Liu Ren, Qi Men, Tai Yi, Liu Yao, tarot and a set of 14 number-divination schools. It says the algorithms run offline through bundled Java, Python and Node runtimes.

Before a calculation it applies a clarification gate: if birth time, place, time zone, gender or house system is missing, the agent receives a question to put to the user instead of guessing. Each result comes with a technique card describing the method, settings and version chain, and every run is stored in a local SQLite archive that can be searched across sessions. A horosa_hecan tool runs several techniques in parallel and requires disagreements to be disclosed.

Reports can be exported as DOCX, PDF, PNG or ICS. Install needs uv and about 5 GB of disk; the full offline runtime is published for macOS on Apple silicon and Windows, with a lighter JavaScript engine for other platforms. The README states it is free and open source under AGPL.

## Features

- **114 techniques:** Covers Western astrology, Chinese metaphysics, tarot and 14 number-divination schools in one install.
- **Fully offline:** Calculations run on your machine with no upload.
- **Clarification gate:** Missing birth details trigger a question for the user rather than a guessed chart.
- **Technique card:** Each result states the method, settings, calculator and version chain.
- **Multi-technique comparison:** horosa_hecan cross-checks techniques and must disclose disagreements.
- **Local record archive:** SQLite full-text search and JSON artifacts keep past runs retrievable.
- **Report export:** Produces DOCX, PDF, JSON and other formats from a reading.

## Good for

- Cast a natal or horary chart from a chat after supplying birth details
- Compare a Bazi reading with a Western transit view
- Retrieve a client's earlier charts by name or date
- Export a formatted reading report as Word or PDF
- Choose an auspicious date with an electional technique

## Install

### Claude Code (Terminal)

```sh
claude mcp add horosa-skill --env HOROSA_JEV_API_KEY='<HOROSA_JEV_API_KEY>' -- npx -y https://github.com/Horace-Maxwell/horosa-skill/releases/download/v0.51.0/horosa-skill-0.51.0.mcpb
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "horosa-skill": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/Horace-Maxwell/horosa-skill/releases/download/v0.51.0/horosa-skill-0.51.0.mcpb"
      ],
      "env": {
        "HOROSA_JEV_API_KEY": "<HOROSA_JEV_API_KEY>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "horosa-skill": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/Horace-Maxwell/horosa-skill/releases/download/v0.51.0/horosa-skill-0.51.0.mcpb"
      ],
      "env": {
        "HOROSA_JEV_API_KEY": "<HOROSA_JEV_API_KEY>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "horosa-skill": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/Horace-Maxwell/horosa-skill/releases/download/v0.51.0/horosa-skill-0.51.0.mcpb"
      ],
      "env": {
        "HOROSA_JEV_API_KEY": "<HOROSA_JEV_API_KEY>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "horosa-skill": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/Horace-Maxwell/horosa-skill/releases/download/v0.51.0/horosa-skill-0.51.0.mcpb"
      ],
      "env": {
        "HOROSA_JEV_API_KEY": "<HOROSA_JEV_API_KEY>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "horosa-skill": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/Horace-Maxwell/horosa-skill/releases/download/v0.51.0/horosa-skill-0.51.0.mcpb"
      ],
      "env": {
        "HOROSA_JEV_API_KEY": "<HOROSA_JEV_API_KEY>"
      }
    }
  }
}
```

## FAQ

### Does it need the internet?

The algorithms run offline once the runtime is installed.

### What does it need to install?

uv, Python 3.12 or newer (managed by uv) and roughly 5 GB of disk space.

### Which platforms get the full runtime?

macOS on Apple silicon and Windows x64; other platforms get a lighter JavaScript engine or can use a gateway.

### What licence is it under?

The README says free and open source under AGPL.

### Can it call a cloud service?

Only an optional decision layer, off by default, set with the HOROSA_JEV variable.

### Is Horosa Skill free?

Yes. Horosa Skill is open source, so you can use and self-host it for free.

### How do I add Horosa Skill to Claude Code?

Run this command in your terminal: claude mcp add horosa-skill --env HOROSA_JEV_API_KEY='<HOROSA_JEV_API_KEY>' -- npx -y https://github.com/Horace-Maxwell/horosa-skill/releases/download/v0.51.0/horosa-skill-0.51.0.mcpb

### What are the best alternatives to Horosa Skill?

The closest alternatives to Horosa Skill are Natal Chart Lab, VedicDost: Vedic Astrology, Kundli & AI Astrologer, AstroLogics, GenesisCore Astrology (Western + Vedic) and Céu Natal.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Natal Chart Lab](https://ai-powered.com/mcp/natal-chart-lab): Natal Chart Lab is an open-source MCP server for astrology.
- [VedicDost: Vedic Astrology, Kundli & AI Astrologer](https://ai-powered.com/mcp/vedicdost-vedic-astrology-kundli-and-ai-astrologer): VedicDost: Vedic Astrology, Kundli & AI Astrologer is a free MCP server for astrology.
- [AstroLogics](https://ai-powered.com/mcp/astrologics): AstroLogics is a freemium MCP server for astrology.
- [GenesisCore Astrology (Western + Vedic)](https://ai-powered.com/mcp/genesiscore-astrology-western-vedic): GenesisCore Astrology (Western + Vedic) is a free MCP server for astrology.
- [Céu Natal](https://ai-powered.com/mcp/ceu-natal): Céu Natal is an open-source MCP server for astrology.
- [OIYO Korea Calculators](https://ai-powered.com/mcp/oiyo-korea-calculators): OIYO Korea Calculators is a free MCP server for finance and payments.
- [Zodiac Compatibility](https://ai-powered.com/mcp/zodiac-compatibility): Zodiac Compatibility is a free MCP server for astrology.
- [12 Chinese Zodiac Signs](https://ai-powered.com/mcp/12-chinese-zodiac-signs): 12 Chinese Zodiac Signs is a free MCP server for astrology.

---
Source: https://ai-powered.com/mcp/horosa-skill
