Swift Tarot MCP Server

A Model Context Protocol (MCP) server that provides tarot card reading functionality. This server allows AI assistants to draw tarot cards, perform multi-card readings, and access the complete tarot deck.

Features

LLMs are notoriously bad at randomness, similar to humans. This MCP server provides more reliable random number generation for tarot readings.

- Flexible Card Drawing: Draw anywhere from 1 to 78 tarot cards in a single request
- Full Deck Access: View all 78 cards in the traditional tarot deck
- Card Images: Fetch base64-encoded images for tarot cards
- Deterministic Testing: Uses seeded random number generation for consistent testing
- Comprehensive Validation: Input validation with proper error handling

Installation

Prerequisites

- Swift 5.9 or later
- macOS 13.0 or later
- Just command runner (optional but recommended)

Install Just (Optional)

brew install just

Build and Install

1. Clone the repository:

git clone <repository-url>

cd swift-tarot-MCP

2. Build and install the server:

just install

This will build the release version and install it to /usr/local/bin/swift-tarot-MCP.

Alternatively, you can build manually:

swift build -c release

sudo cp .build/release/swift-tarot-MCP /usr/local/bin/

Claude Desktop Configuration

To use this MCP server with Claude Desktop, add the following to your Claude Desktop configuration file:

macOS Configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tarot": {
      "command": "swift-tarot-MCP",
      "args": []
    }
  }
}

After Configuration

1. Restart Claude Desktop
2. The tarot tools should now be available in your conversations
3. You can ask Claude to draw tarot cards, perform readings, or show the full deck

Available Tools

draw_cards

Parameters:
- count (optional): Number of cards to draw (1-78, default: 1)

Example usage in Claude:
> "Draw me a tarot card"
> "Draw me 5 tarot cards for a reading"

get_full_deck

Example usage in Claude:
> "Show me the complete tarot deck"

fetch_images

Parameters:
- uris: Array of tarot card URIs to fetch images for

Example usage in Claude:
> "Show me the image for The Fool card"

Development

Available Commands

If you have Just installed, you can use these commands:

```bash