Tarot MCP Server

A Model Context Protocol (MCP) server that provides tarot card reading capabilities to AI assistants like Claude, Cursor, and other MCP-compatible tools.

Features

Complete 78-card Tarot deck with Major and Minor Arcana
Multiple spread layouts including Celtic Cross, Past-Present-Future, and more
Card interpretations with upright and reversed meanings
Intelligent readings with contextual interpretation
Search functionality to find cards by keywords
Daily card draws for daily guidance

Installation

From npm

npm install -g tarot-mcp

From source

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

Configuration

Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

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

If installed locally from source:

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

Cursor

Add to your Cursor settings:

Open Cursor Settings (Cmd+, on macOS, Ctrl+, on Windows/Linux)
Navigate to the "Features" tab
Look for "Model Context Protocol" or "MCP" section
Add the tarot server configuration:

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

VSCode with Continue Extension

If using the Continue extension for VSCode:

Open Continue settings (~/.continue/config.json)
Add the MCP server to the mcpServers section:

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

Other MCP-Compatible Tools

For any tool that supports MCP servers, you generally need:

Command: npx tarot-mcp (if installed from npm) or node /path/to/dist/index.js (if local)
Transport: stdio (standard input/output)
Server Name: tarot

Check your tool's documentation for specific configuration format.

Available Tools

1. `draw_cards`

Draw a specified number of tarot cards.

Parameters:
- count (number): Number of cards to draw (1-78)

2. `perform_reading`

Perform a complete tarot reading with a specific spread.

Parameters:
- spreadId (string): ID of the spread to use
- question (string, optional): Question for the reading

3. `interpret_reading`

Get a detailed interpretation of a tarot reading.

Parameters:
- reading (object): The reading object from perform_reading

4. `get_card_meaning`

Get detailed information about a specific tarot card.

Parameters:
- cardName (string): Name of the card (e.g., "The Fool", "Three of Cups")

5. `list_spreads`

List all available tarot spreads with descriptions.

6. `get_spread_info`

Get detailed information about a specific spread.

Parameters:
- spreadId (string): ID of the spread

7. `daily_card`

Draw a single card for daily guidance.

8. `search_cards`

Search for tarot cards by keyword.

Parameters:
- query (string): Search query

9. `list_all_cards`

List all 78 tarot cards.

Parameters:
- arcana (string, optional): Filter by "major", "minor", or "all"

Available Spreads

single-card: Single Card - Quick insight or daily guidance
past-present-future: Past, Present, Future - Temporal progression
situation-action-outcome: Situation, Action, Outcome - Decision making
mind-body-spirit: Mind, Body, Spirit - Holistic self-reflection
celtic-cross: Celtic Cross - Comprehensive 10-card analysis
relationship-spread: Relationship Spread - 7-card relationship dynamics
career-spread: Career Path - 5-card career guidance
horseshoe: Horseshoe - 7-card general guidance
year-ahead: Year Ahead - 12 cards for each month
decision-making: Decision Making - 5-card decision analysis

Example Usage

In Claude Desktop

Once configured, you can ask Claude to use the tarot tools:

"Draw three tarot cards for me"

"Perform a Celtic Cross reading about my career"

"What does The Fool card mean?"

"Show me all available tarot spreads"

"Do a past-present-future reading about my relationship"

"Search for cards related to 'love'"

"Give me a daily tarot card"

In Cursor

The tarot tools will be available to the AI assistant. You can use them in:

Chat Panel: Ask the AI to perform readings or explain cards
Inline Code Generation: Request tarot-related functionality
Terminal Commands: Use the AI to help interpret readings

Example prompts:

"Use the tarot MCP server to draw a card for today"
"Perform a relationship spread reading"
"List all available tarot spreads"

In VSCode with Continue

After configuration, use commands like:

Type @tarot to specifically use the tarot server
Ask questions like "Draw a Celtic Cross spread"
Request interpretations: "What does the Three of Swords mean?"

Programmatic Usage

You can also interact with the MCP server programmatically:

// Example of calling the MCP server from your application
const reading = await mcp.call('tarot', 'perform_reading', {
  spreadId: 'celtic-cross',
  question: 'What should I focus on this month?'
});

const interpretation = await mcp.call('tarot', 'interpret_reading', {
  reading: reading
});

Development

Building

npm run build

Testing locally

npm run dev

Project Structure

tarot-mcp/
├── src/
│   ├── index.ts          # MCP server implementation
│   ├── types/            # TypeScript type definitions
│   │   └── tarot.ts
│   ├── data/            # Tarot card and spread data
│   │   ├── cards.ts
│   │   └── spreads.ts
│   └── tools/           # Tool implementations
│       └── tarot-tools.ts
├── package.json
├── tsconfig.json
└── README.md

Troubleshooting

Common Issues

Server not connecting
- Ensure the path to the server is correct
- Check that Node.js is installed and accessible
- Verify the configuration file is properly formatted JSON
Commands not working
- Restart your AI tool after adding the configuration
- Check the tool's logs for MCP connection errors
- Ensure you've built the project if running from source
"Tool not found" errors
- The AI tool might need explicit prompting to use the MCP server
- Try prefixing requests with "Use the tarot MCP server to..."

Getting Help

Check the GitHub Issues
Verify your configuration matches the examples above
Ensure you're using the latest version

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Ideas for Contribution

Add more tarot spreads
Enhance card interpretations
Add support for different tarot deck traditions
Implement card combination meanings
Add journaling features
Create visualization tools

License

MIT

Author

Abdul Hamid Achik

Acknowledgments

Tarot card meanings based on traditional Rider-Waite-Smith interpretations
Built with the Model Context Protocol SDK
Inspired by centuries of tarot tradition and modern digital divination tools

Resources

Tarot MCP Server

A Model Context Protocol (MCP) server that provides tarot card reading capabilities to AI assistants like Claude, Cursor, and other MCP-compatible tools.

Features

Complete 78-card Tarot deck with Major and Minor Arcana
Multiple spread layouts including Celtic Cross, Past-Present-Future, and more
Card interpretations with upright and reversed meanings
Intelligent readings with contextual interpretation
Search functionality to find cards by keywords
Daily card draws for daily guidance

Installation

From npm

npm install -g tarot-mcp

From source

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

Configuration

Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

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

If installed locally from source:

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

Cursor

Add to your Cursor settings:

Open Cursor Settings (Cmd+, on macOS, Ctrl+, on Windows/Linux)
Navigate to the "Features" tab
Look for "Model Context Protocol" or "MCP" section
Add the tarot server configuration:

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

VSCode with Continue Extension

If using the Continue extension for VSCode:

Open Continue settings (~/.continue/config.json)
Add the MCP server to the mcpServers section:

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

Other MCP-Compatible Tools

For any tool that supports MCP servers, you generally need:

Command: npx tarot-mcp (if installed from npm) or node /path/to/dist/index.js (if local)
Transport: stdio (standard input/output)
Server Name: tarot

Check your tool's documentation for specific configuration format.

Available Tools

1. `draw_cards`

Draw a specified number of tarot cards.

Parameters:
- count (number): Number of cards to draw (1-78)

2. `perform_reading`

Perform a complete tarot reading with a specific spread.

Parameters:
- spreadId (string): ID of the spread to use
- question (string, optional): Question for the reading

3. `interpret_reading`

Get a detailed interpretation of a tarot reading.

Parameters:
- reading (object): The reading object from perform_reading

4. `get_card_meaning`

Get detailed information about a specific tarot card.

Parameters:
- cardName (string): Name of the card (e.g., "The Fool", "Three of Cups")

5. `list_spreads`

List all available tarot spreads with descriptions.

6. `get_spread_info`

Get detailed information about a specific spread.

Parameters:
- spreadId (string): ID of the spread

7. `daily_card`

Draw a single card for daily guidance.

8. `search_cards`

Search for tarot cards by keyword.

Parameters:
- query (string): Search query

9. `list_all_cards`

List all 78 tarot cards.

Parameters:
- arcana (string, optional): Filter by "major", "minor", or "all"

Available Spreads

single-card: Single Card - Quick insight or daily guidance
past-present-future: Past, Present, Future - Temporal progression
situation-action-outcome: Situation, Action, Outcome - Decision making
mind-body-spirit: Mind, Body, Spirit - Holistic self-reflection
celtic-cross: Celtic Cross - Comprehensive 10-card analysis
relationship-spread: Relationship Spread - 7-card relationship dynamics
career-spread: Career Path - 5-card career guidance
horseshoe: Horseshoe - 7-card general guidance
year-ahead: Year Ahead - 12 cards for each month
decision-making: Decision Making - 5-card decision analysis

Example Usage

In Claude Desktop

Once configured, you can ask Claude to use the tarot tools:

"Draw three tarot cards for me"

"Perform a Celtic Cross reading about my career"

"What does The Fool card mean?"

"Show me all available tarot spreads"

"Do a past-present-future reading about my relationship"

"Search for cards related to 'love'"

"Give me a daily tarot card"

In Cursor

The tarot tools will be available to the AI assistant. You can use them in:

Chat Panel: Ask the AI to perform readings or explain cards
Inline Code Generation: Request tarot-related functionality
Terminal Commands: Use the AI to help interpret readings

Example prompts:

"Use the tarot MCP server to draw a card for today"
"Perform a relationship spread reading"
"List all available tarot spreads"

In VSCode with Continue

After configuration, use commands like:

Type @tarot to specifically use the tarot server
Ask questions like "Draw a Celtic Cross spread"
Request interpretations: "What does the Three of Swords mean?"

Programmatic Usage

You can also interact with the MCP server programmatically:

// Example of calling the MCP server from your application
const reading = await mcp.call('tarot', 'perform_reading', {
  spreadId: 'celtic-cross',
  question: 'What should I focus on this month?'
});

const interpretation = await mcp.call('tarot', 'interpret_reading', {
  reading: reading
});

Development

Building

npm run build

Testing locally

npm run dev

Project Structure

tarot-mcp/
├── src/
│   ├── index.ts          # MCP server implementation
│   ├── types/            # TypeScript type definitions
│   │   └── tarot.ts
│   ├── data/            # Tarot card and spread data
│   │   ├── cards.ts
│   │   └── spreads.ts
│   └── tools/           # Tool implementations
│       └── tarot-tools.ts
├── package.json
├── tsconfig.json
└── README.md

Troubleshooting

Common Issues

Server not connecting
- Ensure the path to the server is correct
- Check that Node.js is installed and accessible
- Verify the configuration file is properly formatted JSON
Commands not working
- Restart your AI tool after adding the configuration
- Check the tool's logs for MCP connection errors
- Ensure you've built the project if running from source
"Tool not found" errors
- The AI tool might need explicit prompting to use the MCP server
- Try prefixing requests with "Use the tarot MCP server to..."

Getting Help

Check the GitHub Issues
Verify your configuration matches the examples above
Ensure you're using the latest version

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Ideas for Contribution

Add more tarot spreads
Enhance card interpretations
Add support for different tarot deck traditions
Implement card combination meanings
Add journaling features
Create visualization tools

License

MIT

Author

Abdul Hamid Achik

Acknowledgments

Tarot card meanings based on traditional Rider-Waite-Smith interpretations
Built with the Model Context Protocol SDK
Inspired by centuries of tarot tradition and modern digital divination tools

Tarot MCP Server

Tarot MCP Server

Features

Installation

From npm

From source

Configuration

Claude Desktop

Cursor

VSCode with Continue Extension

Other MCP-Compatible Tools

Available Tools

1. draw_cards

2. perform_reading

3. interpret_reading

4. get_card_meaning

5. list_spreads

6. get_spread_info

7. daily_card

8. search_cards

9. list_all_cards

Available Spreads

Example Usage

In Claude Desktop

In Cursor

In VSCode with Continue

Programmatic Usage

Development

Building

Testing locally

Project Structure

Troubleshooting

Common Issues

Getting Help

Contributing

Ideas for Contribution

License

Author

Acknowledgments

Resources

Tarot MCP Server

Features

Installation

From npm

From source

Configuration

Claude Desktop

Cursor

VSCode with Continue Extension

Other MCP-Compatible Tools

Available Tools

1. draw_cards

2. perform_reading

3. interpret_reading

4. get_card_meaning

5. list_spreads

6. get_spread_info

7. daily_card

8. search_cards

9. list_all_cards

Available Spreads

Example Usage

In Claude Desktop

In Cursor

In VSCode with Continue

Programmatic Usage

Development

Building

Testing locally

Project Structure

Troubleshooting

Common Issues

Getting Help

Contributing

Ideas for Contribution

License

Author

Acknowledgments

Resources

1. `draw_cards`

2. `perform_reading`

3. `interpret_reading`

4. `get_card_meaning`

5. `list_spreads`

6. `get_spread_info`

7. `daily_card`

8. `search_cards`

9. `list_all_cards`

1. `draw_cards`

2. `perform_reading`

3. `interpret_reading`

4. `get_card_meaning`

5. `list_spreads`

6. `get_spread_info`

7. `daily_card`

8. `search_cards`

9. `list_all_cards`