playbooks

home / mcp / tarot mcp server

Tarot MCP Server

Exposes a complete Tarot deck with spreads, meanings, and daily guidance via MCP for AI assistants.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "abdul-hamid-achik-tarot-mcp": {
      "command": "npx",
      "args": [
        "tarot-mcp"
      ]
    }
  }
}

You can run a Tarot MCP Server that exposes a complete 78-card Tarot deck with advanced spreads and interpretations to your AI assistants. This server enables your tools to draw cards, perform spreads, interpret readings, search for cards by keywords, and provide daily card guidance, all through a simple MCP interface.

How to use

You interact with the Tarot MCP Server through MCP-compatible clients by calling its available tools to perform readings, draw cards, or fetch meanings. Start a reading by selecting a spread, ask a question, and then request an interpretation of that reading. You can also draw a single card for daily guidance, search for cards by keywords, or list all supported spreads to plan your session.

How to install

Prerequisites: You need Node.js and npm installed on your system.

From npm install the Tarot MCP package globally.

npm install -g tarot-mcp

If you prefer to build from source, clone the repository, install dependencies, and build the project locally.

git clone https://github.com/abdul-hamid-achik/tarot-mcp.git
cd tarot-mcp
npm install
npm run build

Configuration

Configure your MCP clients to connect to the Tarot MCP Server using stdio-based commands. The server runs locally via a CLI tool named tarot-mcp, which you can invoke with npm or by running the built index.js directly.

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

If you install locally from source, point to the built entry point with Node.

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

Troubleshooting

If you encounter connection issues, verify that the path to the server is correct, ensure Node.js is installed, and confirm the configuration file uses valid JSON. If commands do not seem to run, restart your MCP-enabled tool after updating the configuration and rebuild if you are running from source.

Development notes

This server exposes a set of tools that you can call programmatically or from MCP-enabled tools. It includes card drawing, readings with multiple spreads, card meanings, and a search feature, all designed to work with AI assistants through the MCP interface.

Available tools

draw_cards

Draw a specified number of tarot cards. Parameters: count (number) - Number of cards to draw (1-78).

perform_reading

Perform a complete tarot reading with a specific spread. Parameters: spreadId (string) and optional question (string).

interpret_reading

Get a detailed interpretation of a tarot reading. Parameters: reading (object) - The reading object from perform_reading.

get_card_meaning

Get detailed information about a specific tarot card. Parameters: cardName (string) - Name of the card.

list_spreads

List all available tarot spreads with descriptions.

get_spread_info

Get detailed information about a specific spread. Parameters: spreadId (string).

daily_card

Draw a single card for daily guidance.

search_cards

Search for tarot cards by keyword. Parameters: query (string).

list_all_cards

List all 78 tarot cards. Parameters: arcana (string, optional) - Filter by 'major', 'minor', or 'all'.

Tarot MCP Server - abdul-hamid-achik/tarot-mcp