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.

🚀 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?

Feature	This Server	Basic Tarot APIs	Generic Card Readers
Research-Based Accuracy	✅ Verified against professional sources	❌ Generic meanings	❌ Simplified interpretations
Advanced Analysis	✅ Elemental, numerical, archetypal	❌ Basic card meanings	❌ Single-layer interpretation
Context Awareness	✅ Question-specific meanings	❌ One-size-fits-all	❌ Generic responses
Professional Spreads	✅ Celtic Cross dynamics	❌ Simple layouts	❌ Basic positioning
MCP Integration	✅ Native MCP + HTTP/SSE	❌ HTTP only	❌ Limited protocols
Production Ready	✅ Docker, health checks, monitoring	❌ Basic deployment	❌ Development-focused
Type Safety	✅ Full TypeScript	❌ JavaScript only	❌ Minimal typing

🚀 Quick Start

Local Development

Clone and Install

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

Build the Project
```
npm run build
```
Run as MCP Server (stdio)
```
npm start
# or
node dist/index.js
```

Run as HTTP Server

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

Development Mode

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

Docker Deployment

Quick Deploy with Script
```
chmod +x deploy.sh
./deploy.sh
```

Manual Docker Build

npm run docker:build
npm run docker:run

Docker Compose

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

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": "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

Build for production
```
npm run build
```

Run with PM2 (recommended)

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

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

Enhanced Interpretations: Deeper psychological analysis and Jungian insights
Timing Predictions: Advanced timing predictions and seasonal influences
Internationalization: Support for multiple languages and cultural variations
Visual Integration: Card imagery and visual representation support
Mobile Integration: React Native or Flutter SDK development

📋 Contribution Process

Fork the repository and create a feature branch
Research thoroughly - All card meanings must be verified against professional sources
Maintain quality - Follow TypeScript best practices and include comprehensive tests
Document changes - Update README and add examples for new features
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