🔮 Tarot MCP Server

A professional-grade Model Context Protocol (MCP) server for Rider-Waite tarot card readings, built with Node.js and TypeScript. This server provides comprehensive tarot functionality through both MCP protocol and HTTP API endpoints, featuring research-based interpretations and advanced reading analysis.

Server config

{
  "command": "npx",
  "args": ["tarot-mcp-server@latest"],
  "env": {
    "NODE_ENV": "production"
  }
}

🚀 Current Implementation Status

✅ FULLY IMPLEMENTED AND WORKING:

• Complete 78-card Rider-Waite deck with detailed interpretations

• 11 professional tarot spreads (Single Card, Three Card, Celtic Cross, Horseshoe, Relationship Cross, Career Path, Decision Making, Spiritual Guidance, Year Ahead, Chakra Alignment, Shadow Work)

• Custom Spread Creation: AI can create custom tarot spreads when existing ones don't fit

• Multi-transport MCP server (stdio, HTTP, SSE)

• Advanced interpretation engine with elemental analysis

• Cryptographically secure card shuffling and drawing

• Context-aware meaning selection

• Professional-grade HTTP API with CORS support

• Docker containerization with health checks

• Comprehensive search and analytics tools

• Session management and reading history

• Full TypeScript implementation with strict typing

• Jest testing framework setup

✨ Features

🃏 Professional Tarot System

• Research-Based Accuracy: Interpretations verified against professional tarot sources (Biddy Tarot, Labyrinthos, classical literature)

• Complete Rider-Waite Deck: Comprehensive card database with detailed meanings, symbolism, astrology, and numerology

• 11 Professional Spreads: Celtic Cross, Relationship Cross, Career Path, Spiritual Guidance, Chakra Alignment, Year Ahead, and more

• Custom Spread Creation: AI can create unlimited custom spreads (1-15 positions) when existing spreads don't fit the specific question or context

• Specialized Reading Analysis: Tailored interpretations for relationships, career, spiritual growth, and energy balancing

• Intelligent Card Combinations: Multi-dimensional analysis including elemental balance, suit patterns, and numerical progressions

🧠 Advanced Interpretation Engine

• Context-Aware Readings: Automatically selects relevant meanings based on question content (love, career, health, spiritual)

• Elemental Analysis: Fire, Water, Air, Earth balance assessment and missing element identification

• Archetypal Patterns: Major Arcana progression analysis and Fool's Journey insights

• Position Dynamics: Celtic Cross relationship analysis (conscious vs subconscious, goal vs outcome)

• Energy Flow Assessment: Three Card spread progression and overall reading energy analysis

🚀 Technical Excellence

• Multi-Transport Support: stdio (MCP), HTTP, and SSE protocols

• Cryptographic Randomness: Fisher-Yates shuffle with crypto-secure random number generation

• 50/50 Fair Distribution: Equal probability for upright and reversed card orientations

• Production Ready: Docker containerization, health checks, and comprehensive error handling

• Session Management: Advanced context tracking and reading history

• RESTful API: Direct HTTP endpoints for seamless integration

• Type Safety: Full TypeScript implementation with strict typing

🎯 Live Reading Example

Here's what a professional Celtic Cross reading looks like:

{
  "question": "What should I know about my career path this year?",
  "cards": [
    {"position": "Present Situation", "card": "The Emperor (upright)", "meaning": "Leadership opportunities and career advancement"},
    {"position": "Challenge", "card": "The Lovers (reversed)", "meaning": "Misaligned career choices or workplace conflicts"},
    {"position": "Foundation", "card": "Ace of Wands (upright)", "meaning": "Creative spark and new opportunities"},
    // ... 7 more cards
  ],
  "analysis": {
    "elementalBalance": "Strong Fire energy suggests action and creativity needed",
    "positionDynamics": "Conscious goals align with subconscious drives",
    "energyFlow": "Progression from challenge to resolution",
    "guidance": "Trust your leadership abilities while addressing relationship conflicts"
  }
}

Key Features Demonstrated:

• ✅ Context-aware interpretations (career-focused meanings)

• ✅ Position relationship analysis (conscious vs subconscious)

• ✅ Elemental balance assessment (Fire energy dominance)

• ✅ Professional guidance and actionable insights

🔮 Professional Tarot Spreads

Our server features 11 specialized tarot spreads designed for different life areas and spiritual practices:

🔮 General Guidance

• Single Card: Daily guidance and quick insights

• Three Card: Past/Present/Future analysis with energy flow

• Celtic Cross: Comprehensive 10-card life analysis

• Horseshoe: 7-card situation guidance with obstacles and advice

💕 Relationships & Personal

• Relationship Cross: 7-card relationship dynamics analysis

🚀 Career & Life Path

• Career Path: 6-card professional development guidance

• Decision Making: 5-card choice evaluation and guidance

• Year Ahead: 13-card annual forecast with monthly insights

🧘 Spiritual & Energy Work

• Spiritual Guidance: 6-card spiritual development and higher self connection

• Chakra Alignment: 7-card energy center analysis and healing

• Shadow Work: 5-card psychological integration and growth

Each spread includes:

• Specialized Analysis: Tailored interpretation methods for each spread type

• Position Dynamics: Understanding relationships between card positions

• Energy Assessment: Elemental balance and flow analysis

• Professional Guidance: Actionable insights and spiritual wisdom

🏆 Why Choose This Tarot Server?

🚀 Quick Start

Local Development

1. Clone and Install

   git clone https://git.moraxcheng.me/Morax/tarot-mcp.git
   cd tarot-mcp
   npm install

2. Build the Project

   npm run build

3. Run as MCP Server (stdio)

   npm start
   # or
   node dist/index.js

4. Run as HTTP Server

   npm run start:http
   # or
   node dist/index.js --transport http --port 3000

5. Development Mode

   npm run dev:http  # HTTP server with hot reload
   npm run dev       # stdio server with hot reload

Docker Deployment

1. Quick Deploy with Script

   chmod +x deploy.sh
   ./deploy.sh

2. Manual Docker Build

   npm run docker:build
   npm run docker:run

3. Docker Compose

   npm run docker:compose
   # or
   docker-compose up -d

4. With Traefik (optional)

   docker-compose --profile traefik up -d

📡 API Endpoints

When running in HTTP mode, the following endpoints are available:

Health & Info

• GET /health - Health check with service status

• GET /api/info - Server information, capabilities, and available tools

Tarot Cards

• GET /api/cards - List all cards with filtering options

  • ?category=all|major_arcana|minor_arcana|wands|cups|swords|pentacles

• GET /api/cards/:cardName - Get detailed card information

  • ?orientation=upright|reversed (default: upright)

Professional Readings

• POST /api/reading - Perform a comprehensive tarot reading

  {
    "spreadType": "single_card|three_card|celtic_cross|horseshoe|relationship_cross|career_path|decision_making|spiritual_guidance|year_ahead|chakra_alignment|shadow_work",
    "question": "Your specific question here",
    "sessionId": "optional-session-id-for-tracking"
  }

• POST /api/custom-spread - Create and perform a custom tarot spread

  {
    "spreadName": "Your Custom Spread Name",
    "description": "What this spread explores",
    "positions": [
      {
        "name": "Position Name",
        "meaning": "What this position represents"
      }
    ],
    "question": "Your specific question",
    "sessionId": "optional-session-id"
  }

• GET /api/spreads - List all available spread types with descriptions

Advanced Features

• Celtic Cross Analysis: 10-card comprehensive reading with position dynamics

• Three Card Flow: Past/Present/Future with energy progression analysis

• Elemental Balance: Automatic analysis of Fire, Water, Air, Earth energies

• Context-Aware Interpretations: Meanings selected based on question content

• Advanced Card Search: Multi-criteria search with keyword, suit, element, and arcana filtering

• Similarity Analysis: Find cards with related meanings and themes

• Database Analytics: Comprehensive statistics and quality metrics

• Secure Randomization: Cryptographically secure card drawing and shuffling

MCP Protocol

• GET /sse - Server-Sent Events endpoint for MCP clients

• POST /mcp - HTTP-based MCP endpoint for direct protocol communication

🛠️ MCP Tools

The server provides 8 comprehensive MCP tools for professional tarot reading and analysis:

get_card_info

Get comprehensive information about a specific tarot card including symbolism, astrology, and numerology.

{
  "cardName": "The Fool",
  "orientation": "upright"
}

Returns: Detailed card meanings for general, love, career, health, and spiritual contexts.

list_all_cards

List all available tarot cards with filtering and categorization.

{
  "category": "major_arcana|minor_arcana|wands|cups|swords|pentacles|all"
}

Returns: Organized card listings with keywords and brief descriptions.

perform_reading

Perform a professional tarot reading with advanced interpretation analysis.

{
  "spreadType": "single_card|three_card|celtic_cross|horseshoe|relationship_cross|career_path|decision_making|spiritual_guidance|year_ahead|chakra_alignment|shadow_work",
  "question": "What should I know about my career path this year?",
  "sessionId": "optional-session-id"
}

Features:

• Context-aware meaning selection based on question content

• Elemental balance analysis (Fire, Water, Air, Earth)

• Suit pattern recognition and interpretation

• Position dynamics analysis (Celtic Cross)

• Energy flow assessment (Three Card)

• Relationship compatibility analysis (Relationship Cross)

• Career readiness assessment (Career Path)

• Chakra energy balance evaluation (Chakra Alignment)

• Spiritual development guidance (Spiritual Guidance)

• Annual forecasting (Year Ahead)

search_cards

Search for tarot cards using various criteria like keywords, suit, element, etc.

{
  "keyword": "love",
  "suit": "cups",
  "arcana": "minor",
  "element": "water",
  "orientation": "upright",
  "limit": 10
}

Features:

• Keyword search across meanings, keywords, and symbolism

• Filter by suit, arcana, element, number, and orientation

• Flexible search criteria with customizable result limits

find_similar_cards

Find cards with similar meanings to a given card.

{
  "cardName": "The Fool",
  "limit": 5
}

Features:

• Semantic similarity analysis

• Meaning-based card relationships

• Customizable result limits

get_database_analytics

Get comprehensive analytics and statistics about the tarot card database.

{
  "includeRecommendations": true
}

Features:

• Complete database statistics

• Card distribution analysis

• Quality metrics and recommendations

• Database completeness assessment

get_random_cards

Get random cards with optional filtering for practice and exploration.

{
  "count": 3,
  "suit": "wands",
  "arcana": "major",
  "element": "fire"
}

Features:

• Cryptographically secure randomization

• Optional filtering by suit, arcana, or element

• Customizable card count

create_custom_spread

Create a custom tarot spread and draw cards for it. Perfect for AI when no existing spread fits the specific needs.

{
  "spreadName": "AI Decision Making Spread",
  "description": "A custom spread designed to help AI make decisions when no existing spread fits the situation",
  "positions": [
    {
      "name": "Current Situation",
      "meaning": "The present state of affairs that needs to be addressed"
    },
    {
      "name": "Hidden Influences",
      "meaning": "Unseen factors affecting the situation"
    },
    {
      "name": "Guidance",
      "meaning": "Wisdom and advice for making the best decision"
    }
  ],
  "question": "What is the best approach for this unique situation?",
  "sessionId": "optional-session-id"
}

Features:

• Create custom spreads with 1-15 positions

• Define custom position names and meanings

• Automatic card drawing with cryptographically secure randomization

• Full interpretation with position-specific analysis

• Session management support

• Perfect for AI when existing spreads don't fit the specific question or context

🔧 Configuration

Command Line Options

node dist/index.js [options]

Options:
  --transport <type>    Transport type: stdio, http, sse (default: stdio)
  --port <number>       Port for HTTP/SSE transport (default: 3000)
  --help, -h           Show help message

Environment Variables

• NODE_ENV - Environment (development/production)

• PORT - Server port (default: 3000)

🎯 MCP Client Integration

Cursor IDE

Add to your Cursor mcp.json:

{
  "mcpServers": {
    "tarot": {
      "command": "npx",
      "args": ["tarot-mcp-server@latest"]
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "tarot": {
      "command": "node",
      "args": ["/path/to/tarot-mcp/dist/index.js"]
    }
  }
}

HTTP-based MCP Clients

For clients supporting HTTP MCP:

{
  "mcpServers": {
    "tarot": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

SSE-based MCP Clients

For clients supporting Server-Sent Events:

{
  "mcpServers": {
    "tarot": {
      "url": "http://localhost:3000/sse"
    }
  }
}

📚 Usage Examples

Professional Reading Examples

Single Card Daily Guidance

curl -X POST http://localhost:3000/api/reading \
  -H "Content-Type: application/json" \
  -d '{
    "spreadType": "single_card",
    "question": "What energy should I embrace today?"
  }'

Features: Elemental analysis, daily guidance, spiritual insights

Three Card Relationship Reading

curl -X POST http://localhost:3000/api/reading \
  -H "Content-Type: application/json" \
  -d '{
    "spreadType": "three_card",
    "question": "How can I improve my relationships?"
  }'

Features: Past/Present/Future flow, energy progression analysis

Celtic Cross Career Reading

curl -X POST http://localhost:3000/api/reading \
  -H "Content-Type: application/json" \
  -d '{
    "spreadType": "celtic_cross",
    "question": "What should I know about my career path this year?"
  }'

Features: 10-card comprehensive analysis, position dynamics, conscious vs subconscious insights

Relationship Cross Analysis

curl -X POST http://localhost:3000/api/reading \
  -H "Content-Type: application/json" \
  -d '{
    "spreadType": "relationship_cross",
    "question": "How can I improve my relationship with my partner?"
  }'

Features: 7-card relationship dynamics, compatibility assessment, unity/division analysis

Career Path Guidance

curl -X POST http://localhost:3000/api/reading \
  -H "Content-Type: application/json" \
  -d '{
    "spreadType": "career_path",
    "question": "What should I know about my career development?"
  }'

Features: 6-card professional analysis, skills assessment, opportunity identification

Chakra Energy Alignment

curl -X POST http://localhost:3000/api/reading \
  -H "Content-Type: application/json" \
  -d '{
    "spreadType": "chakra_alignment",
    "question": "How can I balance my energy centers?"
  }'

Features: 7-card chakra analysis, energy balance assessment, spiritual healing guidance

Custom Spread Creation

curl -X POST http://localhost:3000/api/custom-spread \
  -H "Content-Type: application/json" \
  -d '{
    "spreadName": "AI Decision Making Spread",
    "description": "A custom spread designed to help AI make decisions when no existing spread fits the situation",
    "positions": [
      {
        "name": "Current Situation",
        "meaning": "The present state of affairs that needs to be addressed"
      },
      {
        "name": "Hidden Influences",
        "meaning": "Unseen factors affecting the situation"
      },
      {
        "name": "Option A",
        "meaning": "One potential direction or choice"
      },
      {
        "name": "Option B",
        "meaning": "An alternative direction or choice"
      },
      {
        "name": "Guidance",
        "meaning": "Wisdom and advice for making the best decision"
      }
    ],
    "question": "What is the best approach for creating a new tarot spread when existing ones don'\''t fit?"
  }'

Features: Unlimited custom spread creation (1-15 positions), AI-driven card drawing, position-specific interpretations

Card Information Queries

Detailed Card Information

curl "http://localhost:3000/api/cards/The%20Fool?orientation=upright"

Browse Cards by Category

curl "http://localhost:3000/api/cards?category=major_arcana"
curl "http://localhost:3000/api/cards?category=wands"

List Available Spreads

curl "http://localhost:3000/api/spreads"

Advanced Search and Analytics

Search Cards by Keyword

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "search_cards",
      "arguments": {
        "keyword": "love",
        "suit": "cups",
        "limit": 5
      }
    }
  }'

Find Similar Cards

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "find_similar_cards",
      "arguments": {
        "cardName": "The Lovers",
        "limit": 3
      }
    }
  }'

Get Database Analytics

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "get_database_analytics",
      "arguments": {
        "includeRecommendations": true
      }
    }
  }'

Get Random Cards for Practice

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "get_random_cards",
      "arguments": {
        "count": 3,
        "arcana": "major"
      }
    }
  }'

🏗️ Architecture

Professional Tarot Engine

src/
├── index.ts              # Multi-transport entry point (stdio/HTTP/SSE)
├── http-server.ts        # Production HTTP server with CORS and error handling
├── tarot-server.ts       # Core tarot server with MCP tool integration
└── tarot/
    ├── types.ts          # Comprehensive TypeScript definitions
    ├── card-data.ts      # Research-verified Rider-Waite card database
    ├── card-manager.ts   # Advanced card data management and search
    ├── spreads.ts        # Professional spread definitions and layouts
    ├── reading-manager.ts # Advanced interpretation engine with:
    │                     #   - Elemental balance analysis
    │                     #   - Suit pattern recognition
    │                     #   - Numerical progression interpretation
    │                     #   - Archetypal pattern analysis
    │                     #   - Context-aware meaning selection
    └── session-manager.ts # Session tracking and reading history

Key Components

Advanced Interpretation Engine

• Multi-Dimensional Analysis: Individual cards + combinations + overall themes

• Professional Methods: Based on research from Biddy Tarot, Labyrinthos, and classical sources

• Context Awareness: Question-specific meaning selection (love, career, health, spiritual)

• Elemental Analysis: Fire, Water, Air, Earth balance and missing element identification

Production-Ready Infrastructure

• Multi-Transport Support: stdio (MCP), HTTP REST API, Server-Sent Events

• Docker Containerization: Complete deployment with health checks and monitoring

• Error Handling: Comprehensive error responses and logging

• Type Safety: Full TypeScript implementation with strict mode

🧪 Testing & Quality Assurance

Test Suite

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode during development
npm run test:watch

# Code quality checks
npm run lint
npm run format

Quality Metrics

• Unit Tests: Card manager, reading logic, and interpretation engine

• Integration Tests: API endpoints and MCP tool functionality

• Type Safety: 100% TypeScript with strict mode enabled

• Code Coverage: Comprehensive test coverage for core functionality

• Professional Validation: Interpretations verified against established tarot sources

Research Validation

• Accuracy Verification: Cross-referenced with Biddy Tarot, Labyrinthos, and classical literature

• Traditional Compliance: Adherence to established Rider-Waite traditions

• Professional Standards: Implementation of methods used by certified tarot readers

• Symbolic Integrity: Proper interpretation of traditional symbols and imagery

🚢 Deployment

Production Deployment

1. Build for production

   npm run build

2. Run with PM2 (recommended)

   npm install -g pm2
   pm2 start dist/index.js --name tarot-mcp -- --transport http --port 3000

3. Or use Docker

   docker run -d -p 3000:3000 --name tarot-mcp tarot-mcp

Reverse Proxy Setup

Example Nginx configuration:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

We welcome contributions to improve the Tarot MCP Server! Here's how you can help:

🎯 Priority Areas

1. Enhanced Interpretations: Deeper psychological analysis and Jungian insights

2. Timing Predictions: Advanced timing predictions and seasonal influences

3. Internationalization: Support for multiple languages and cultural variations

4. Visual Integration: Card imagery and visual representation support

5. Mobile Integration: React Native or Flutter SDK development

📋 Contribution Process

1. Fork the repository and create a feature branch

2. Research thoroughly - All card meanings must be verified against professional sources

3. Maintain quality - Follow TypeScript best practices and include comprehensive tests

4. Document changes - Update README and add examples for new features

5. Submit pull request with detailed description and test coverage

🔬 Research Standards

• Primary Sources: Biddy Tarot, Labyrinthos, classical tarot literature

• Verification: Cross-reference meanings with multiple professional sources

• Traditional Accuracy: Maintain adherence to established Rider-Waite traditions

• Professional Language: Use authentic tarot terminology and phrasing

🧪 Testing Requirements

• Unit Tests: All new functionality must include comprehensive tests

• Integration Tests: API endpoints and MCP tool validation

• Type Safety: Maintain 100% TypeScript coverage with strict mode

• Documentation: Include usage examples and API documentation

🗺️ Roadmap

📅 Version 2.0 (Planned)

• Enhanced Interpretations: Deeper psychological analysis and Jungian insights

• Timing Predictions: Seasonal influences and time-based guidance

• Enhanced AI: Machine learning for pattern recognition in readings

• Visual Integration: Card imagery and interactive visual representations

📅 Version 2.5 (Future)

• Multi-Language Support: Internationalization for global accessibility

• Cultural Variations: Support for different tarot traditions and interpretations

• Advanced Analytics: Reading history analysis and personal growth tracking

• Mobile SDK: Native mobile application support

📅 Version 3.0 (Vision)

• Psychological Integration: Advanced Jungian analysis and psychological tarot methods

• Real-Time Collaboration: Shared readings and collaborative interpretation

• AI-Enhanced Insights: Advanced pattern recognition and personalized guidance

• Blockchain Integration: Decentralized reading verification and authenticity

🔮 About This Professional Tarot Implementation

Research-Based Accuracy

This server implements the traditional Rider-Waite tarot deck with interpretations verified against multiple professional sources:

• Biddy Tarot: Professional Celtic Cross methodology and advanced reading techniques

• Labyrinthos: Traditional symbolism and classical interpretations

• Classical Tarot Literature: Historical meanings and established correspondences

• Professional Reader Methods: Advanced combination interpretation techniques

Comprehensive Card Database

✅ COMPLETE: All 78 cards of the Rider-Waite deck are fully implemented with extensive information for each card:

• Multi-Context Meanings: General, love, career, health, and spiritual interpretations

• Orientation Specific: Detailed upright and reversed meanings beyond simple opposites

• Symbolic Analysis: Comprehensive interpretation of traditional Rider-Waite imagery

• Astrological Correspondences: Planetary and zodiacal associations

• Numerological Significance: Spiritual and practical number meanings

• Elemental Associations: Fire, Water, Air, Earth energies and their interactions

Advanced Reading Methods

• Celtic Cross Dynamics: Professional 10-card analysis with position relationships

• Three Card Flow: Energy progression and temporal analysis

• Elemental Balance: Missing element identification and recommendations

• Archetypal Patterns: Major Arcana progression and spiritual themes

• Context Awareness: Question-specific meaning selection and relevance

Professional Quality

The interpretations maintain traditional tarot wisdom while providing:

• Authentic Language: Professional tarot terminology and phrasing

• Actionable Guidance: Practical advice combined with spiritual insights

• Depth and Nuance: Multi-layered analysis beyond surface meanings

• Accessibility: Clear explanations suitable for both beginners and experienced readers