The Fortuneteller's Hand

What The Fortuneteller's Hand does

The Fortuneteller's Hand turns Claude into the facilitator for a solo, card-driven journaling RPG. The player and Claude take turns developing a story, with the player describing events and Claude interpreting cards, Omens, and the consequences of choices. The underlying game is an original tabletop RPG that is still being developed.

A session begins with the player meeting the Fortuneteller and choosing where that meeting takes place. The game then draws one card from each of four suits. These readings establish four facets of the character, expressed as phrases that help shape the character's psychology and future story. A separate Goal card must be interpreted before the journey begins.

Scenes follow a repeating pattern: establish the current location, draw a card to reveal what is developing, and narrate what happens next. When a scene involves another heart, something concealed, or a need for luck, the player can call for an Omen. The game also supports conflict with fate through its Defiance rules.

How it works

The Fortuneteller's Hand is designed around creative journaling rather than competition. Its character prompts—Motivation, Ends, Seek, and Carry—provide starting material, but the player can follow them closely or allow the story to develop in another direction. Describing more of the scene gives Claude more material to interpret and continue.

Claude runs the table while the player supplies decisions and narration. The server provides the game structure and state needed to track the session, including the character, cards drawn, and any debt owed. The project includes separate rules, a walkthrough, and a transcript of a sample session for players who want more detail before starting.

Setup and configuration

The simplest installation uses the versioned .mcpb package from the project's GitHub release. Double-clicking the package opens an installation prompt in Claude Desktop. After confirming, fully restart Claude Desktop, open a new chat, and attach the start_game prompt. That prompt asks for the player's character name before play begins.

Running from source requires Python and uv. From the repository directory, run uv sync, then add an MCP server entry to Claude Desktop's developer configuration. The documented command uses uv run --directory with the absolute repository path and main.py. Restart Claude Desktop, enable the fortuneteller connector, create a new chat, and attach start_game. Filling in the player_name value does not submit the prompt automatically; send it after the prompt appears as a chip.

Tools and capabilities

• Starts a new game with the start_game prompt.
• Builds a character from four card-derived facets.
• Guides interpretation of a Goal card.
• Draws cards for scenes and reads what they suggest.
• Calls Omens when the story requires a direct question to fate.
• Supports Defiance when fate turns against the character.
• Keeps game state in memory during the active session.

Limitations and notes

The Fortuneteller's Hand is a narrative journaling game, so its value depends on the player's descriptions and willingness to develop the story. It is not presented as a game focused on winning. The complete mechanics are maintained in the repository's RULES.md, while HOW_TO_PLAY.md provides a fuller introduction.

The privacy policy states that the server collects no data, shares nothing with third parties, and retains nothing. Character information, drawn cards, and debt exist only in memory for the duration of the session and are discarded afterward. The provided installation instructions document Claude Desktop; no other client is specified in the supplied material.