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 [email protected].
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.