Tarot

Provides a multi-transport MCP server with a complete Rider-Waite tarot deck, 11 spreads, custom spread creation, and a robust HTTP API.

typescript

5

GitHub Stars

typescript

Language

5 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You can access a professional Tarot MCP Server that delivers Rider-Waite tarot interpretations through MCP as well as HTTP endpoints. It offers a complete card deck, 11 professional spreads, context-aware readings, cryptographically secure shuffling, session tracking, and production-ready tooling so you can integrate tarot readings into your applications with confidence.

How to use

You connect to the Tarot MCP Server using an MCP client over stdio, HTTP, or Server-Sent Events. With an MCP client, you can request standardized readings, explore card data, create custom spreads, and perform advanced analyses such as elemental balance and position dynamics. Use the server to generate professional, context-aware readings for questions about career, relationships, spirituality, or personal growth. You can also retrieve card information and browse available spreads to plan your reading session.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system.

Clone the project repository.
Install dependencies.
Build the project.
Run the server as an MCP stdio service.

Configuration & usage notes

The server is designed to run in multiple transports. It is built in TypeScript and ships with production-ready features such as health checks, error handling, session management, and a RESTful HTTP API with CORS support.

Key concepts you will use after installation include starting the server, choosing a transport (stdio, http, or sse), and issuing readings or data queries through the respective endpoints. Remember to manage sessions if you want to track reading history and context across multiple requests.

Endpoints and basic usage notes

When the server runs in HTTP mode, you can access health, info, cards, and readings endpoints. Use the health endpoint to verify the service is up, query card data to learn about individual cards, and perform readings using the dedicated reading endpoints. For advanced features, you can create custom spreads and access spread definitions.

Security and stability

The server includes cryptographically secure randomization for shuffling, robust error handling, and strict type safety through TypeScript. Docker deployment and health checks are provided for production stability.

Usage examples overview

Typical usage includes requesting a reading for a given spread type and question, or querying card information. You can also perform advanced searches, find similar cards, or generate random cards for practice.

Available tools

get_card_info

Get comprehensive card information including symbolism, astrology, numerology, and context-specific meanings.

list_all_cards

List all cards with filtering by category, suit, arcana, and other attributes.

perform_reading

Execute a professional tarot reading with context-aware interpretations and elemental balance analysis.

search_cards

Search cards by keywords, suit, arcana, element, orientation, and other criteria.

find_similar_cards

Find cards with similar meanings or themes to a given card.

get_database_analytics

Return comprehensive analytics on the tarot card database including distributions and quality metrics.

get_random_cards

Draw cryptographically secure random cards with optional filtering.

create_custom_spread

Create and draw cards for a custom spread with 1-15 positions and full interpretations.