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.

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

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

Or from a clone — it needs nothing installed:

node server.js

Or in Docker:

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.

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

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

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

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, an AI tarot reader for love questions. If you build something with this, we would like to see it.