The Fortuneteller's Hand MCP server

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 HOWTOPLAY.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.

Running it

Quick install

the file itself). It'll open an install prompt in Claude Desktop.

1. Download fortunetellers-hand-0.1.1.mcpb somewhere findable.
2. Double-click it (don't drag it into a chat window — just double-click

character name, then you're off.

1. Confirm the install.
2. Fully quit and reopen Claude Desktop.
3. Start a new chat, and pull in the start_game prompt — it'll ask for a

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"]
       }
     }
   }

"fortuneteller."

1. Fully quit and restart Claude Desktop.
2. Click the + icon near the message box → Connectors → enable

hit enter — attaching it doesn't submit it on its own.

1. Start a new chat and pull in the start_game prompt.
2. When it asks for your character's name (player_name), fill that in.
3. Once the prompt attaches as a chip above the message box, click send or

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?

Shortened. The full README is on GitHub.