# TarotAPI MCP > TarotAPI connects your AI client directly to a complete, structured 78-card tarot deck. It lets you pull random cards for daily guidance or run complex multi-card spreads—like the Celtic Cross—and get full interpretations on demand. You can also search the whole deck using specific keywords or meanings. ## Overview - **Category:** artificial-intelligence - **Price:** Free - **Tags:** tarot, fortune-telling, card-meanings, random-generation, esoteric-data ## Description You gotta hook your AI client up with TarotAPI to get access to a complete, structured 78-card tarot deck. Forget general knowledge—this server gives you verified data for every single major and minor arcana card. When you run these tools, you're not just getting vague vibes; you’re pulling specific interpretations and keywords directly from the API structure. To start up, you can use `get_api_info` to pull basic meta-information on how the server is set up. If you need a full inventory of what’s in the deck before running anything else, run `list_all_cards`. That tool returns the total catalog of all 78 cards, listing their official names, assigned numbers, and unique short identifiers that you'll need later. When it comes to reading specific cards, your options are pretty deep. If you know exactly which card you want—say, The Tower or The Lovers—you use `get_card`. Just feed it the card’s short name (like 'ar01'), and it spits out all the detailed info: keywords, a full description, its meaning when upright, and what it means if it's reversed. It gives you the whole package. If you need to find cards based on something other than their name—maybe you’re looking for a card related to 'change' or 'communication'—you use `search_cards`. This tool searches the entire deck using general text queries, letting you pinpoint every card whose meaning or keyword matches what you type in. You can search by upright meanings or reversed interpretations. For quick reads, you don’t gotta do much work. If you just want a single random card for daily reflection, run `get_random_card`. It immediately generates one completely arbitrary card, perfect for quick guidance without needing any inputs from your side. When you need more than one card—like running a full Celtic Cross spread or even just looking at past/present/future sequences—you call `get_multiple_random_cards`. This tool pulls several random cards all at once, letting your agent handle structured layouts that require multiple specific placements. These tools mean you control the entire reading process. You use `list_all_cards` to build your knowledge base; then you pull a single card with `get_card`; or if you're doing a spread, you hit it with `get_multiple_random_cards`. If all that fails, you can always narrow things down by querying the data using `search_cards`, making sure every interpretation you pass to your user is backed up by structured data. You don’t have to guess; you just call the right tool. ## Tools ### get_api_info Retrieves basic meta-information about the TarotAPI server setup. ### get_card Fetches detailed data for a specific card using its short name, including upright and reversed meanings and keywords. ### get_random_card Generates a single, completely random card suitable for quick daily guidance or reflection. ### get_multiple_random_cards Pulls several random cards simultaneously; this is useful for structured spreads like the Celtic Cross layout. ### list_all_cards Returns the full catalog of all 78 cards, listing their names, numbers, and available identifiers. ### search_cards Searches the entire deck based on general text queries or specific meanings (upright/reversed). ## Prompt Examples **Prompt:** ``` Pull a card for my daily reading. ``` **Response:** ``` Your card for today is **The Empress** (III) — Major Arcana. Keywords: fertility, femininity, beauty, nature, abundance. This card suggests nurturing energy and creative growth. Embrace beauty and abundance in your life today. ``` **Prompt:** ``` Give me a three-card past/present/future reading. ``` **Response:** ``` Your three-card spread: **Past**: The Tower — Sudden change and upheaval. A structure in your life crumbled, making way for new growth. **Present**: Four of Pentacles — Holding on tight to resources. You may be feeling protective of what you have. **Future**: The Star — Hope, renewal, and inspiration. After the storm, peace and healing are coming. ``` **Prompt:** ``` What does The Fool card mean in tarot? ``` **Response:** ``` **The Fool (0)** — Major Arcana. Keywords: innocence, beginnings, freedom, innocence, a free spirit. Upright meaning: new beginnings, optimism, trust, and the start of a journey. Reversed meaning: recklessness, risk-taking, naivety. Fortune telling: a new adventure is beginning; embrace the unknown with an open heart. ``` ## Capabilities ### Get Single Card Details Retrieves a card's full data—keywords, description, upright/reversed meaning, and image—given its short name (e.g., 'ar01'). ### Generate Multi-Card Spreads Pulls multiple random cards for structured readings like the Celtic Cross or simple three-card sequences. ### Pull Daily Guidance Card Gets one random card suitable for quick, daily reflection without needing specific inputs. ### Search by Meaning or Keyword Finds all cards in the deck that match a given text query, whether it's an upright meaning or general keyword. ### List All Cards Returns a full inventory of all 78 cards, including their names and unique short identifiers for later use. ## Use Cases ### Creating Daily Devotional Content A wellness app needs daily content. Instead of writing a new reading every day, the agent calls `get_random_card` to pull today's card. It then passes that single card to the AI client, which formats the keywords and meaning into a ready-to-post article. ### Designing RPG Quests A game designer needs a plot device. They ask the agent for a 'three-card spread' using `get_multiple_random_cards`. The resulting Past/Present/Future cards become three mandatory elements of the quest narrative, ensuring symbolic consistency. ### Building an Educational Quiz Tool A student needs to learn card meanings. They use `list_all_cards` first, then prompt the agent to 'search for all cards related to finance.' The tool runs `search_cards`, giving a clean list of relevant concepts and associated cards. ### Debugging Card Identifiers A developer is building an inventory viewer. They start by running `list_all_cards` just to ensure they have the correct short names (like 'swac' vs. 'Ace of Cups'), preventing runtime errors when calling `get_card`. ## Benefits - Structured Interpretation: Instead of vague text, the API returns dedicated fields for Upright Meaning, Reversed Meaning, Keywords, and general descriptions. This consistency is critical when building reliable content loops. - Versatile Readings: The `get_multiple_random_cards` tool lets you run complex spreads (like Past/Present/Future) in one call. You get a structured reading immediately, not just a list of cards. - Precision Search: Use `search_cards` to find every card that mentions a specific concept—say, 'challenge' or 'growth.' This is better than searching a general knowledge base because you are confined to the 78-card canon. - Efficiency for Daily Content: The `get_random_card` tool eliminates setup time. It provides fresh, guided content instantly, perfect for daily email digests or blog prompts. - Full Deck Mapping: Running `list_all_cards` gives you all the necessary identifiers and metadata to build a complete front-end browsing experience without guessing card codes. ## How It Works The bottom line is that you get clean, structured tarot data without having to manually cross-reference 78 cards across multiple websites or databases. 1. First, your AI agent uses `list_all_cards` to confirm the available card identifiers (e.g., 'swac', 'ar01'). 2. Next, you prompt the agent with a request—for example, "Give me a three-card spread.". The agent then calls `get_multiple_random_cards`. 3. You receive structured JSON output containing the card names, their associated meanings (upright/reversed), and keywords for immediate use. ## Frequently Asked Questions **How do I get card details for a specific card using TarotAPI?** Use the `get_card` tool. You must provide the short name (like 'ar01' or 'swac'). This returns all structured data, including both upright and reversed meanings. **Can I run a three-card spread using get_multiple_random_cards?** Yes. `get_multiple_random_cards` is designed for this. It pulls multiple random cards simultaneously, making it perfect for structured layouts like Past/Present/Future. **What if I want to find all cards related to 'courage'?** Use `search_cards`. You can query the tool with keywords or specific meanings. This will return every card in the deck that matches your search criteria. **Is there a way to see what cards are available for me to use?** Run `list_all_cards`. This returns a complete inventory of all 78 tarot cards, giving you their names and the unique short identifiers needed for other tools. **Does TarotAPI support reversed card meanings?** Yes. The `get_card` tool explicitly includes fields for both upright and reversed interpretations for every major arcana card. **Using the get_random_card tool, how can I pull a single card for quick daily guidance?** The tool instantly returns one random tarot card. The response provides the full meaning, keywords, and interpretations right away. This is perfect when you need immediate reflection or general advice without specifying a particular card. **When I use the get_api_info tool, what technical details about TarotAPI should I expect?** It provides essential metadata for the API. This information helps your AI client understand the service's structure and available endpoints before making a functional call. **If I try to run the get_card tool with an invalid short name, what error do I receive?** The system returns a clear error message. This response specifies that the card identifier is incorrect and guides you toward using valid formats like 'ar01' or 'swac'. **Do I need an API key or account?** No! TarotAPI is completely free and open with no authentication required. **How many cards are in the deck?** The deck contains all 78 traditional tarot cards: 22 Major Arcana and 56 Minor Arcana (Wands, Cups, Swords, Pentacles). **Can I do a three-card past/present/future reading?** Yes! Use `get_multiple_random_cards` with count=3 to draw three cards for a past/present/future spread.