love-oracle-tarot-dataset

# Love Oracle Tarot Dataset & MCP Server

All 78 Rider–Waite–Smith tarot cards with **love and relationship keywords in 22 languages**, plus
arcana, suit, element and yes/no polarity — as a JSON file **and** as an MCP server that runs
offline over it. No signup, free to use commercially under
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

```
curl -O https://www.loveoracle.app/dataset/love-tarot.json
```

## MCP server

Three read-only tools, zero dependencies, zero network calls — everything is answered from the JSON
file in this repository.

| Tool | What it does |
|---|---|
| `search_tarot_cards` | Find cards by name in any of the 22 languages; returns the slugs the other tools take |
| `get_tarot_card_love_meaning` | One card: upright, reversed, yes/no leaning, arcana, suit, element |
| `draw_tarot_cards` | Draw 1–10 cards without replacement, each ~30% likely to land reversed, with their love meanings |

```json
{
  "mcpServers": {
    "love-oracle-tarot": {
      "command": "npx",
      "args": ["-y", "love-oracle-tarot"]
    }
  }
}
```

Or from a clone — it needs nothing installed:

```bash
node server.js
```

Or in Docker:

```bash
docker build -t love-oracle-tarot . && docker run -i --rm love-oracle-tarot
```

**Want the long-form interpretations too?** They are not in the dataset and so are not served here.
What a card says as someone's feelings, what it means about an ex, and the answers to the
most-asked love questions live on the site — reachable through the hosted MCP server at
`https://www.loveoracle.app/api/mcp` (Streamable HTTP, no auth), listed in the official registry as
[`app.loveoracle/tarot`](https://registry.modelcontextprotocol.io/v0.1/servers?search=app.loveoracle/tarot).

Public tarot datasets exist. Every one we could find is English-only. This one carries
**1,716 keyword pairs** across `en, es, pt, fr, de, it, nl, da, no, fi, pl, hu, tr, ru, ja, ko, zh,
zh-TW, th, vi, id, hi` — the part nobody wants to redo.

## Shape

```json
{
  "slug": "the-lovers",
  "name": "The Lovers",
  "arcana": "major",
  "number": 6,
  "suit": null,
  "element": null,
  "yes_no": { "upright": "yes", "reversed": "no" },
  "image": "https://www.loveoracle.app/deck/the-lovers.webp",
  "url": "https://www.loveoracle.app/cards/the-lovers",
  "love": {
    "en": { "name": "The Lovers", "upright": "deep union, a real choice of the heart",
            "reversed": "disharmony, misaligned values, avoidance of choice" },
    "ja": { "name": "恋人たち", "upright": "深い結びつき、心からの選択",
            "reversed": "不調和、ずれた価値観、選ぶことからの逃避" }
  }
}
```

| Field | Notes |
|---|---|
| `slug` | Stable identifier, always the English name. Never changes. Use it as your key |
| `arcana` / `number` / `suit` | `major` 0–21, `minor` 1–14 (11 Page, 12 Knight, 13 Queen, 14 King) |
| `element` | Suits only — `water`, `fire`, `air`, `earth`. **`null` for every major**, deliberately: their elemental attributions differ between the Golden Dawn, Marseille and modern schools, and we would rather leave a field empty than state a contested one as fact |
| `yes_no` | Polarity for a one-card yes/no draw. Reversing a card flips it |
| `image` | The 1909 scan. Public domain worldwide, no condition attached |
| `love.<lang>` | Localized card name plus upright and reversed keywords |

```bash
jq '.cards[] | select(.slug=="the-lovers") | .love.es' love-tarot.json
jq -r '.cards[] | select(.yes_no.upright=="yes") | .slug' love-tarot.json   # the 43 "yes" cards
```

## Two honest caveats

- **These keywords are written for love and relationship questions**, not general divination. A
  career-focused app will want different phrasing.
- **The 21 non-English languages were machine-translated** from the English source and have **not
  been reviewed by native speakers**. Structure and coverage are reliable — zero missing rows, zero
  silent fallbacks to English. Idiom in Thai and Vietnamese may not be. Corrections welcome:
  open an issue or mail hello@loveoracle.app.

## Licence

[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Use it commercially, modify it, ship it.
The one condition is credit:

```
Tarot data from Love Oracle — https://www.loveoracle.app
CC BY 4.0
```

Card artwork is Pamela Colman Smith's 1909 edition, public domain worldwide, and carries no
condition at all.

## Also available

- **Canonical file, always current:** https://www.loveoracle.app/dataset/love-tarot.json
- **Documentation:** https://www.loveoracle.app/dataset
- **MCP server** (Streamable HTTP, read-only, no auth): `https://www.loveoracle.app/api/mcp` —
  three tools: `search_tarot_cards`, `get_tarot_card_love_meaning`, `get_love_question_answer`
- **Markdown:** every public page answers to `Accept: text/markdown`, or fetch `/md/<path>` directly

```bash
curl -H "Accept: text/markdown" https://www.loveoracle.app/cards/the-lovers
curl https://www.loveoracle.app/md/es/cards/the-lovers
```

## What is not in here

The long-form interpretations — what each card means as someone's feelings, what it says about an
ex, the FAQs — stay on the card pages. This repository is the compact factual layer.

---

Maintained alongside [Love Oracle](https://www.loveoracle.app), an AI tarot reader for love
questions. If you build something with this, we would like to see it.