Tarot MCP Server

A Model Context Protocol (MCP) server that provides tarot card reading capabilities to AI assistants like Claude, Cursor, and other MCP-compatible tools.

Features

• Complete 78-card Tarot deck with Major and Minor Arcana

• Multiple spread layouts including Celtic Cross, Past-Present-Future, and more

• Card interpretations with upright and reversed meanings

• Intelligent readings with contextual interpretation

• Search functionality to find cards by keywords

• Daily card draws for daily guidance

Installation

From npm

From source

Configuration

Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

If installed locally from source:

Cursor

Add to your Cursor settings:

1. Open Cursor Settings (Cmd+, on macOS, Ctrl+, on Windows/Linux)

2. Navigate to the "Features" tab

3. Look for "Model Context Protocol" or "MCP" section

4. Add the tarot server configuration:

VSCode with Continue Extension

If using the Continue extension for VSCode:

1. Open Continue settings (~/.continue/config.json)

2. Add the MCP server to the mcpServers section:

Other MCP-Compatible Tools

For any tool that supports MCP servers, you generally need:

• Command: npx tarot-mcp (if installed from npm) or node /path/to/dist/index.js (if local)

• Transport: stdio (standard input/output)

• Server Name: tarot

Check your tool's documentation for specific configuration format.

Available Tools

1. draw_cards

Draw a specified number of tarot cards.

• Parameters:

  • count (number): Number of cards to draw (1-78)

2. perform_reading

Perform a complete tarot reading with a specific spread.

• Parameters:

  • spreadId (string): ID of the spread to use

  • question (string, optional): Question for the reading

3. interpret_reading

Get a detailed interpretation of a tarot reading.

• Parameters:

  • reading (object): The reading object from perform_reading

4. get_card_meaning

Get detailed information about a specific tarot card.

• Parameters:

  • cardName (string): Name of the card (e.g., "The Fool", "Three of Cups")

5. list_spreads

List all available tarot spreads with descriptions.

6. get_spread_info

Get detailed information about a specific spread.

• Parameters:

  • spreadId (string): ID of the spread

7. daily_card

Draw a single card for daily guidance.

8. search_cards

Search for tarot cards by keyword.

• Parameters:

  • query (string): Search query

9. list_all_cards

List all 78 tarot cards.

• Parameters:

  • arcana (string, optional): Filter by "major", "minor", or "all"

Available Spreads

• single-card: Single Card - Quick insight or daily guidance

• past-present-future: Past, Present, Future - Temporal progression

• situation-action-outcome: Situation, Action, Outcome - Decision making

• mind-body-spirit: Mind, Body, Spirit - Holistic self-reflection

• celtic-cross: Celtic Cross - Comprehensive 10-card analysis

• relationship-spread: Relationship Spread - 7-card relationship dynamics

• career-spread: Career Path - 5-card career guidance

• horseshoe: Horseshoe - 7-card general guidance

• year-ahead: Year Ahead - 12 cards for each month

• decision-making: Decision Making - 5-card decision analysis

Example Usage

In Claude Desktop

Once configured, you can ask Claude to use the tarot tools:

In Cursor

The tarot tools will be available to the AI assistant. You can use them in:

1. Chat Panel: Ask the AI to perform readings or explain cards

2. Inline Code Generation: Request tarot-related functionality

3. Terminal Commands: Use the AI to help interpret readings

Example prompts:

• "Use the tarot MCP server to draw a card for today"

• "Perform a relationship spread reading"

• "List all available tarot spreads"

In VSCode with Continue

After configuration, use commands like:

• Type @tarot to specifically use the tarot server

• Ask questions like "Draw a Celtic Cross spread"

• Request interpretations: "What does the Three of Swords mean?"

Programmatic Usage

You can also interact with the MCP server programmatically:

Development

Building

Testing locally

Project Structure

Troubleshooting

Common Issues

1. Server not connecting

   • Ensure the path to the server is correct

   • Check that Node.js is installed and accessible

   • Verify the configuration file is properly formatted JSON

2. Commands not working

   • Restart your AI tool after adding the configuration

   • Check the tool's logs for MCP connection errors

   • Ensure you've built the project if running from source

3. "Tool not found" errors

   • The AI tool might need explicit prompting to use the MCP server

   • Try prefixing requests with "Use the tarot MCP server to..."

Getting Help

• Check the GitHub Issues

• Verify your configuration matches the examples above

• Ensure you're using the latest version

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Ideas for Contribution

• Add more tarot spreads

• Enhance card interpretations

• Add support for different tarot deck traditions

• Implement card combination meanings

• Add journaling features

• Create visualization tools

License

MIT

Author

Abdul Hamid Achik

Acknowledgments

• Tarot card meanings based on traditional Rider-Waite-Smith interpretations

• Built with the Model Context Protocol SDK

• Inspired by centuries of tarot tradition and modern digital divination tools

Resources

• MCP Documentation

• Tarot History and Meanings

• GitHub Repository