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.

Terminal

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

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

Terminal

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

config.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. Use it commercially, modify it, ship it. The one condition is credit:

Code

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

Terminal

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.