Skip to content
MCP server

Horosa Skill

Offline server with 114 Chinese metaphysics and Western astrology chart techniques

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
macOS, Windows, Linux
Runs
Locally
Version
0.51.0
Listing updated
today

Similar MCP servers

About Horosa Skill

Horosa Skill is an open-source MCP server for astrology. It runs locally on your machine and is started by your AI client.

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.

Install

Run in a 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

Add to claude_desktop_config.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>"
      }
    }
  }
}

Add to ~/.cursor/mcp.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>"
      }
    }
  }
}

Add to .vscode/mcp.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>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.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>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "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>"
      }
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

Configuration

  • HOROSA_RUNTIME_ROOTOffline runtime directory (default ~/.horosa/runtime or %LOCALAPPDATA%\\Horosa\\runtime)
  • HOROSA_SKILL_DATA_DIRLocal runs / reports / SQLite directory (default ~/.horosa-skill)
  • HOROSA_JEVOptional cloud decision layer (TypeSafe Jev): off (default, fully local) / shadow / enforce
  • HOROSA_JEV_API_KEYTypeSafe Jev API key; only read when HOROSA_JEV is not off

What it does

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

Pricing

Open source

Horosa Skill 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.

How AIPoweredBot checks servers