The Fortuneteller's Hand — an RPG MCP Server

An MCP server that acts as a role playing game and GM using the rules of The Fortuneteller's Hand, an original tabletop RPG that I am currently working on. Claude reads the cards, casts the omens, and runs the table; the player and Claude will take turns narrating the story that develops.

What playing feels like

A short version, before you install anything: you sit with the Fortuneteller first — where you meet them is the one choice made before any card is drawn. Four suits become four facets of who you are; the Fortuneteller draws one card from each and speaks what it reveals, and you build a character from those four phrases. Once you have your character, you must interpret your Goal card before you set out.

From there, every scene works the same way: decide where you are, flip a card to see what's stirring, narrate forward. The moment the story reaches another heart, something hidden, or needs a turn of luck, you stop and ask fate directly by calling an Omen. Fate can turn against you, too; when it does, you can fight it.

This is, at heart, a creative journaling game. The real pleasure is in the narration you and the Fortuneteller build together, not in winning anything. Motivation, Ends, Seek, and Carry aren't rules to obey; they're seeds, four starting points for your character's psychology and the shape of the story ahead. Follow them where they lead, or let the story wander somewhere else. The more you describe, the more the story gives back.

That's the shape of it. Full mechanics in RULES.md; a gentler, fuller walkthrough in HOW_TO_PLAY.md; a full transcript of an actual session in 08-2026-Play-Example.md. If you ever lose track of your Goal or your four facets partway through a story, just ask the Fortuneteller to remind you.

Related MCP server: mcp-tarot-draw

Running it

Quick install

1. Save learnMCP.mcpb somewhere findable.

2. Double-click it (don't drag it into a chat window — just double-click the file itself). It'll open an install prompt in Claude Desktop.

3. Confirm the install.

4. Fully quit and reopen Claude Desktop.

5. Start a new chat, and pull in the start_game prompt — it'll ask for a character name, then you're off.

Run from source

Requires Python and uv.

1. uv sync inside this directory.

2. In Claude Desktop: Settings → Developer → Edit Config, and add:

   {
     "mcpServers": {
       "fortuneteller": {
         "command": "uv",
         "args": ["run", "--directory", "/absolute/path/to/learnMCP", "main.py"]
       }
     }
   }

3. Fully quit and restart Claude Desktop.

4. Click the + icon near the message box → Connectors → enable "fortuneteller."

5. Start a new chat and pull in the start_game prompt.

6. When it asks for your character's name (player_name), fill that in.

7. Once the prompt attaches as a chip above the message box, click send or hit enter — attaching it doesn't submit it on its own.

Influences

This project draws from a few places. The Omens' two-dice reading, comparing rather than summing, owes a real debt to Ironsworn by Shawn Tomkin, which I absolutely LOVE. The Defiance ritual, "Not Like This," borrows its five-dice, three-roll, keep-what-you-want shape from Yahtzee (which was stolen from the Puerto Rican game "Jenerala"). As a journaling game, this owes a lot to Thousand Year Old Vampire by Tim Hutchings, one of the games that proved solo, prompt-driven play could carry real weight. Incredible game! And finally, Max Moon has shaped the tone of this project throughout. I adore everything Max Moon creates.

Curious about the build?

This started as a way to learn the Model Context Protocol in a way that would interest me. The tool/resource/prompt choices, the state design, a few real bugs found and fixed along the way, these are all written up in DESIGN.md. If you have any questions or wish me to fix, or add anything, please contact me.

Privacy Policy

• Data collection: This MCP collects nothing.

• Usage and storage: Nothing is stored. All game state (your character, cards drawn, debt owed) exists only in memory for the length of your session and is discarded when it ends.

• Third-party sharing: Nothing is shared with any third party, because nothing is collected in the first place.

• Data retention: Nothing is retained.

• Contact information: maria@mariasaha.com