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.
LLMs are notoriously bad at randomness, similar to humans. This MCP server provides more reliable random number generation for tarot readings.
- Single Card Draw: Draw a random tarot card for quick insights
- Multi-Card Readings: Draw multiple cards (1-78) for more detailed readings
- Full Deck Access: View all 78 cards in the traditional tarot deck
- Deterministic Testing: Uses seeded random number generation for consistent testing
- Comprehensive Validation: Input validation with proper error handling
- Swift 5.9 or later
- macOS 13.0 or later
- Just command runner (optional but recommended)
brew install just
- Clone the repository:
git clone <repository-url>
cd swift-tarot-MCP
- 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/
To use this MCP server with Claude Desktop, add the following to your Claude Desktop configuration file:
Edit ~/Library/Application Support/Claude/claude_desktop_config.json
:
{
"mcpServers": {
"tarot": {
"command": "swift-tarot-MCP",
"args": []
}
}
}
- Restart Claude Desktop
- The tarot tools should now be available in your conversations
- You can ask Claude to draw tarot cards, perform readings, or show the full deck
Draws a single random tarot card.
Example usage in Claude:
"Draw me a tarot card"
Draws multiple tarot cards for a reading.
Parameters:
count
(optional): Number of cards to draw (1-78, default: 3)
Example usage in Claude:
"Draw me 5 tarot cards for a reading"
Returns all 78 cards in the tarot deck.
Example usage in Claude:
"Show me the complete tarot deck"
If you have Just installed, you can use these commands:
# Build the project (debug by default)
just build
# Build for release
just build release
# Run tests
just test
# Run tests with verbose output
just test --verbose
# Lint the code
just lint
# Auto-fix linting issues
just lint --fix
# Run the server locally
just run
# Clean build artifacts
just clean
# Install to system PATH
just install
# Remove from system PATH
just uninstall
Without Just, you can use these Swift commands:
# Build debug
swift build
# Build release
swift build -c release
# Run tests
swift test
# Run linting
swift package plugin --allow-writing-to-package-directory swiftlint
The project includes comprehensive tests covering:
- Tarot card data structures and validation
- Deck composition and card drawing
- Server handler functionality
- MCP protocol compliance
- Deterministic behavior with seeded RNG
Run tests with:
just test
# or
swift test
The project is structured as:
- TarotMCPCore: Core library containing tarot card logic and MCP server implementation
- TarotMCP: Executable that runs the MCP server using stdio transport
TarotCard
: Enum representing major and minor arcana cardsTarotDeck
: Static methods for card drawing and deck managementTarotServer
: MCP server implementationTarotServerHandler
: Handles MCP tool calls and routing
Cards are returned in a simple, readable format:
You drew:
- The Fool
You drew 3 cards:
- The Magician
- Two of Cups
- King of Swords
This project is licensed under the MIT License - see the LICENSE file for details.