Love Oracle — Tarot

What Love Oracle — Tarot does

Love Oracle — Tarot exposes a compact tarot dataset through the Model Context Protocol. The local package contains all 78 Rider–Waite–Smith cards, with stable English slugs, localized names, love and relationship keywords, card classification, and yes/no polarity. It is intended for questions about romance and relationships, not for career-focused readings or general divination.

The dataset covers English, Spanish, Portuguese, French, German, Italian, Dutch, Danish, Norwegian, Finnish, Polish, Hungarian, Turkish, Russian, Japanese, Korean, Simplified Chinese, Traditional Chinese, Thai, Vietnamese, Indonesian, and Hindi. The 21 non-English language sets were machine-translated from English and have not been reviewed by native speakers.

How it works

The local server reads the JSON file included with the project and answers requests without network calls. Its three tools are read-only:

• search_tarot_cards finds cards by name in any supported language and returns slugs for subsequent requests.
• get_tarot_card_love_meaning returns one card’s upright and reversed keywords, yes/no leaning, arcana, suit, and element.
• draw_tarot_cards selects one to ten cards without replacement. Each card has an approximately 30% chance of being reversed, and the response includes its love meaning.

Major arcana cards have no element value. Suits use water, fire, air, or earth. The JSON also includes image and card-page URLs, and the card slug is a stable English identifier.

A separate hosted endpoint at https://www.loveoracle.app/api/mcp uses Streamable HTTP and requires no authentication. The hosted service includes get_love_question_answer for site-based answers, while the repository’s local dataset does not contain those long-form interpretations.

Setup and configuration

Configure an MCP client to launch the package with npx -y love-oracle-tarot. Alternatively, clone the repository and run node server.js; the README states that the local server needs nothing installed beyond the runtime. Docker is also supported by building the included image and running it interactively.

Love Oracle — Tarot has no required environment variables, signup flow, or network dependency when run locally. The canonical dataset can also be downloaded directly from https://www.loveoracle.app/dataset/love-tarot.json for applications that need to read the JSON without MCP.

Tools and capabilities

Use the search tool when a client needs to resolve a localized card name to the stable slug. Use the card lookup tool for deterministic metadata and upright or reversed relationship keywords. Use the draw tool for one-card or multi-card readings, with no duplicate cards in a draw.

The dataset contains 1,716 keyword pairs. Its yes/no field records upright and reversed polarity, so reversing a card changes the polarity used for a one-card yes/no reading. Card artwork references the 1909 Pamela Colman Smith edition, which the README identifies as public domain worldwide.

Limitations and notes

The local server does not provide long-form interpretations about someone’s feelings, an ex, or frequently asked love questions. Those materials remain on the Love Oracle website and are not part of the repository dataset.

Love Oracle — Tarot is focused on relationship language. Non-English translations may contain idiomatic issues, especially in Thai and Vietnamese, because they have not received native-speaker review. Commercial use and modification are allowed under CC BY 4.0, with attribution to Love Oracle and its website required for the tarot data.