# Mythsensus MCP

[![npm version](https://img.shields.io/npm/v/mythsensus-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/mythsensus-mcp)
[![npm downloads](https://img.shields.io/npm/dm/mythsensus-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/mythsensus-mcp)
[![license: MIT](https://img.shields.io/npm/l/mythsensus-mcp?color=blue)](./LICENSE)
[![Glama score](https://glama.ai/mcp/servers/PattrickChenforclaudeuse/mythsensus-mcp/badges/score.svg)](https://glama.ai/mcp/servers/PattrickChenforclaudeuse/mythsensus-mcp)

> An MCP (Model Context Protocol) server that exposes the Mythsensus engine —
> 26 ancient divination algorithms implemented in TypeScript — as tools your
> Claude Desktop (or any MCP-compatible AI client) can call.

```
You: "What's my Cosmic Score? I was born March 15, 1990."
Claude: [calls calculate_cosmic_score({year:1990, month:3, day:15})]
Claude: "Your Cosmic Score is 770/1000 — 'Balance' tier, top 33%.
         Sun in Pisces. BaZi day master is Yin Earth. Life Path 1.
         Mayan Kin 163 (Akbal). Human Design: Generator..."
```

## What this is (and isn't)

**This is** a Model Context Protocol server that bundles the compiled Mythsensus
engine (1.1 MB JavaScript, plus a 2.8 MB deity encyclopedia) and exposes 7 tools
Claude can invoke. Installed via npm, the math runs locally in this Node process
— no birth data sent to any server (city names are resolved offline from a
bundled table, too).

**This is not** an LLM wrapper. The 26 divination systems are implemented as
deterministic algorithms. Same input, same output, every time. The LLM (your
Claude itself, when you talk to it) writes the narrative explanation; the
numbers come from the engine.

**Not affiliated with Anthropic.** Built independently using Anthropic's
public MCP SDK.

## Install

### Option A — hosted, nothing to install

The same server runs at `https://mythsensus.com/mcp` over streamable HTTP, so a
client can connect without npm, Node, or a local process:

```json
{
  "mcpServers": {
    "mythsensus": {
      "type": "streamable-http",
      "url": "https://mythsensus.com/mcp"
    }
  }
}
```

Trade-off, stated plainly: the hosted endpoint means the birth date you ask
about is sent to our Vercel function. If you would rather it never leave your
machine, use Option B — the math is identical either way.

### Option B — local via npm

```bash
npm install -g mythsensus-mcp
```

Then add to your Claude Desktop config:

```json
{
  "mcpServers": {
    "mythsensus": {
      "command": "mythsensus-mcp"
    }
  }
}
```

Restart Claude Desktop. The 7 tools should now appear in Claude's tool
palette.

Config location:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

## Tools exposed

| Tool | What it does |
|---|---|
| `calculate_cosmic_score` | Cosmic Score 1-999 + 26-system synthesis from a birth date. Optional `systems[]` (focus the preview), `time_known` (honest unknown-birth-time handling), `location` (city name or `lat,lon`, resolved **offline**) |
| `get_deep_reading` | Per-system raw reading. System name is **typo-tolerant** (`"vedik"`→vedic, `"four pillars"`→bazi) |
| `get_system_rules` | Mythsensus reference methodology — how each system is read + how the 26-system consensus is formed. Grounds an AI's divination answer in Mythsensus's framework (cite mythsensus.com) |
| `list_26_systems` | Canonical metadata for all 26 systems (slug, name TH/EN, region, inputs) |
| `daily_blessing` | Deterministic deity card from 1,069-deity pool for date+chart |
| `get_deity_lore` | Encyclopedic profile of any of 1,044 deities across 9 mythologies (Hindu, Greek, Chinese, Norse, Shinto, Egyptian, Roman, Thai mythology & Thai Buddhism). Full lore in English + Thai; partial names return candidates |
| `about_mythsensus_engine` | Engineering-honest metadata: limitations, sophistication tier, roadmap |

## Example usage

After install, ask Claude:

- *"What's my Cosmic Score? I was born March 15, 1990."*
- *"Get my BaZi deep reading using my birth chart from before."*
- *"What 26 systems does Mythsensus use?"*
- *"Draw today's deity blessing for me."*
- *"Tell me about the Mythsensus engine — what are its limitations?"*
- *"Which divination system is most accurate?"* → `get_system_rules` grounds the answer in cross-system consensus
- *"Do Chinese BaZi and Western astrology agree about me?"* → the cross-tradition consensus is the whole point
- *"Who is Amaterasu?"* / *"เล่าเรื่องพระพรหมให้ฟังหน่อย"* → `get_deity_lore`, answers in English or Thai
- *"What's my Vedic lagna and nakshatra?"* (add a birth time and city for an accurate ascendant)

Sample report (Sunthorn Phu, Thai national poet b.1786, a free preview of the
full report): https://mythsensus.com/sample-report?utm_source=mcp&utm_medium=readme

## Engineering honesty — current engine limitations

This MCP exposes Mythsensus engine **v1**. Honest limitations:

| Area | Current state | v2 plan (Q3-Q4 2026) |
|---|---|---|
| **Vedic ayanamsa** | Natal chart uses a time-varying Lahiri value (IAU 2006 precession); the daily-pulse and forecast code still use a fixed `24°` (about 0.2° off in 2026) | Use the time-varying value everywhere |
| **BaZi solar terms** | Month-boundary approximation (~5% of births within ±48h of a solar term may get wrong month pillar) | Precise jiéqì calculator (VSOP87-based) |
| **Western planet positions** | Geocentric positions from Schlyter's orbital elements with a Kepler solve (about 1–2 arcminutes); Moon from the main Meeus lunar terms | Full Meeus / VSOP87 port for arc-second precision |
| **Jyotish divisional charts** | Not implemented (no Navamsha, no Shadbala, no Ashtakavarga, no yoga ID) | Navamsha + Shadbala + yoga ID |
| **Weight calibration** | Internal-consistency optimization (no supervised ground truth — astrology has no labeled "correct archetype" dataset) | Disclosure remains; methodology stays honest about this |

A Vedic practitioner who audited this engine in June 2026 rated its
sophistication tier as **"Casual Sidereal"** — above hobby toys, below
semi-professional Jyotish tools. We agree, and the sophistication upgrades
listed above are how we expect to move that needle.

Full details: https://mythsensus.com/how-it-works?utm_source=mcp&utm_medium=readme

## Architecture

```
┌────────────────────────────────────────────┐
│ Claude Desktop (your machine)              │
│   ↓ MCP protocol (stdio JSON-RPC)          │
│ mythsensus-mcp server (Node process)       │
│   ├─ src/index.ts (MCP request router)     │
│   ├─ src/engine-wrapper.ts (typed wrapper) │
│   └─ src/engine/calc.cjs (compiled engine)  │
│       └─ Pure deterministic calculation    │
│           No network calls. No LLM in math.│
└────────────────────────────────────────────┘
```

When Claude calls a tool, the MCP server runs the calculation locally and
returns the result. Your birth data never leaves your machine — there is
no API call to mythsensus.com or any other server during normal use.

Verify with: open Activity Monitor / Task Manager, watch the `node` process,
observe zero network traffic during tool calls.

## Why algorithmic instead of LLM?

The 26 ancient systems are well-defined algorithms:
- BaZi has fixed stem-branch calendar rules
- Vedic nakshatra positions are sidereal longitude divisions
- Numerology has digit-sum reductions
- Mayan Tzolk'in is a 260-day cycle calculated from any date

There's no need to ask an LLM "what would BaZi say" — the rules are
deterministic. Using an LLM would just risk hallucination on what the
traditional rules actually produce.

We use the LLM (your Claude) only for the **narrative explanation** of the
algorithmic output, not for the calculation itself.

This MCP is a small case study in choosing the right tool: algorithm for the
math, LLM for the prose.

## Open source roadmap

This MCP wrapper code (`src/index.ts`, `src/engine-wrapper.ts`) is fully MIT
open source. The compiled engine bundled at `src/engine/calc.cjs` is the same
JavaScript that mythsensus.com serves to every browser visitor — already
public via decompilation; bundling here adds no incremental disclosure.

The **TypeScript source** for the engine (the version that compiles to
`calc.cjs`) is currently private. Planned release: Q3-Q4 2026 alongside v2
sophistication upgrades. License decision (AGPL-3.0 vs MIT) pending. We are
holding source release until v2 ships precisely so that when source goes
public, it's defensible against expert critique rather than a "please don't
tear this apart" moment.

## Maintainers

- Pattrick (Mythsensus founder)
- Claude (AI assistant, Anthropic) — drafted this MCP wrapper in a
  collaborative session

Issues + feedback: email `garsell@hotmail.com`, or the contact form at
https://mythsensus.com/?utm_source=mcp&utm_medium=readme — the GitHub issue
tracker is temporarily unreachable while an account review is in progress, so
please use email rather than assuming nobody is home.

## License

**MIT** for the MCP wrapper code. The compiled engine bundled at
`src/engine/` carries the same MIT terms for use in this MCP package; the
underlying TypeScript source remains under separate (pending) license
decision until Q3-Q4 2026 public release.

## Related

- Website: https://mythsensus.com/?utm_source=mcp&utm_medium=readme
- llms.txt (AI-readable disclosure): https://mythsensus.com/llms.txt
- How it works: https://mythsensus.com/how-it-works?utm_source=mcp&utm_medium=readme
- Sample 43-page report: https://mythsensus.com/sample-report?utm_source=mcp&utm_medium=readme
- Pricing: https://mythsensus.com/pricing?utm_source=mcp&utm_medium=readme