DEV Community

Merva Yalçın
Merva Yalçın

Posted on

Build a tarot reader in Node.js with an open 78-card dataset (no scraping)

#opensource #node #beginners #javascript

I wanted tarot card meanings as clean, structured data for a side project, and quickly hit the usual wall: the good interpretations live in long blog posts, and nobody wants to scrape and parse that. So I ended up packaging all 78 cards as an open, MIT-licensed dataset with npm and Python packages (and an MCP server, more on that at the end).

This post is a quick, practical tour: install it, pull a card, build a 3-card spread, and see where else the data lives. No scraping, no API key.

Install 

npm install tarot-card-meanings
Enter fullscreen mode Exit fullscreen mode

It ships with TypeScript types, has zero dependencies, and includes upright, reversed, love, career, and yes/no fields for every Major and Minor Arcana card.

Quick start 

const tarot = require('tarot-card-meanings');

// Pull a random card
const card = tarot.getRandomCard();
console.log(card.name);     // e.g. "The Star"
console.log(card.upright);  // upright meaning
console.log(card.reversed); // reversed meaning

// Look up a specific card
const fool = tarot.getCard('The Fool');
console.log(fool.love);     // love-context interpretation
console.log(fool.career);   // career-context interpretation

// A built-in yes/no reading
const reading = tarot.getYesOrNo();
console.log(`${reading.card}: ${reading.answer}`);
Enter fullscreen mode Exit fullscreen mode

Every card object has the same shape, so you can render it however you like.

Build a 3-card spread

The classic past / present / future spread is just three unique cards. Here is a tiny helper that draws without repeats:

const tarot = require('tarot-card-meanings');

function drawSpread(positions) {
  const deck = [...tarot.getAllCards()];
  return positions.map((label) => {
    const i = Math.floor(Math.random() * deck.length);
    const card = deck.splice(i, 1)[0]; // remove so it can't repeat
    return { position: label, ...card };
  });
}

const spread = drawSpread(['Past', 'Present', 'Future']);
for (const c of spread) {
  console.log(`\n${c.position}: ${c.name}`);
  console.log(c.upright);
}
Enter fullscreen mode Exit fullscreen mode

That is the whole core of a reading app. Swap the position labels for ['Situation', 'Obstacle', 'Advice'] and you have a decision spread instead.

Same data in Python

If your stack is Python, the identical dataset is on PyPI:

pip install tarot-card-meanings
Enter fullscreen mode Exit fullscreen mode

For the ML / data crowd

The raw dataset is also published on Hugging Face and archived with a DOI, so it is citable in a paper or notebook:

It is handy as a small, clean, labeled text corpus for embedding/semantic-search demos.

Bonus: let an AI assistant read tarot (MCP)

Because Model Context Protocol is having a moment, I also wrapped the dataset in an MCP server so an AI assistant can query card meanings as a tool:

Point a compatible client at it and your assistant can pull meanings and spreads on demand instead of hallucinating them.

See it running

If you want to see the data powering a real UI before you build your own, there is a free no-signup reader here: https://deckaura.com/pages/free-tarot-reading

All of the above is open and MIT licensed by Deckaura; the package source and issues are on GitHub, and there is a full index of the open data and tools at deckaura.com/pages/ai-data-sources. PRs and label corrections welcome.

Happy building, and if you make something with it I would love to see it in the comments.

Top comments (1)

Collapse
 
frank_signorini profile image
Frank •

It's great you found a clean dataset!