Hearts MCP Server

A Model Context Protocol server that lets you play the classic Hearts game against AI.

Features

• Full Hearts rules: passing, trick-taking, hearts breaking, Queen of Spades
• Shoot the Moon detection and scoring
• Smart AI opponents with moon shooting/blocking strategies
• Unicode card symbols (♠♥♦♣)
• Mid-round penalty tracking and moon threat alerts
• Card counting via trick history

Installation

Claude Code

# Via npx (recommended)
claude mcp add hearts -- npx -y hearts-mcp-server

# Or global install
npm install -g hearts-mcp-server
claude mcp add hearts -- hearts-mcp-server

From source

git clone https://github.com/wj1918/hearts-mcp-server.git
cd hearts-mcp-server
npm install
npm run build
npm link

Then add to your MCP config:

claude mcp add hearts -- hearts-mcp-server

Tools

| Tool | Description | |------|-------------| | create_game | Start a new game. You sit South against 3 AI opponents. | | pass_cards | Pass 3 cards during the passing phase. | | play_card | Play a card on your turn. AI opponents auto-play after you. | | get_game_state | View your hand, current trick, scores, legal plays, and moon threats. | | get_legal_plays | List the cards you can legally play. | | get_scores | Get cumulative scores and round-by-round breakdown. | | get_trick_history | Review all completed tricks this round for card counting. | | list_games | List all active games. |

How to Play

Once configured, just ask your AI agent to play Hearts:

"Let's play hearts"

The agent will deal the cards, show your hand, and guide you through each step:

1. Passing — The agent shows your hand and suggests which 3 cards to pass. You can accept the suggestion or pick your own.
2. Playing — Each turn, the agent shows the current trick, your hand, and legal plays with strategic advice. Just name the card you want to play (e.g. "play the Queen of Spades" or "♠Q").
3. Between turns — AI opponents play automatically. The agent reports what they played and who won each trick.
4. Scoring — The agent tracks points, warns about moon threats, and shows round summaries.

You can also ask things like:

• "What cards have been played?"
• "Show me the scores"
• "What are my legal plays?"

Card Format

Three input formats are supported:

| Format | Example | Description | |--------|---------|-------------| | Unicode symbol + rank | ♠Q, ♣2, ♥10, ♦A | Symbol prefix | | Letter + rank | SQ, C2, H10, DA | Letter prefix (case-insensitive) | | Rank + letter | QS, 2C, 10H, AD | Letter suffix (case-insensitive) | | Rank only | Q, 3, 10 | When suit is unambiguous from legal plays |

• Ranks: 2, 3, 4, 5, 6, 7, 8, 9, 10, J, Q, K, A
• Suits: C (Clubs), D (Diamonds), S (Spades), H (Hearts)
• If only one suit is possible, you can type just the rank (e.g. "Q" instead of "♠Q")

Example Turn

Trick 8: North won with ♠A (+1 pt, West dumped ♥8). North now at 4 penalty pts, 8 tricks, still threatening the moon!

Now North leads ♥Q — going straight for hearts! East plays ♥5.

              North (AI)
              ♥Q (lead)

  West (AI)                   East (AI)
     —                          ♥5

              South (You)
                 ?

         ┌──────────────┐
Trick 9  │  N: ♥Q       │
         │  E: ♥5       │
         │  S: ?        │
         │  W: waiting  │
         └──────────────┘

┌───────┬───────┬──────┬─────────────┬──────┬────────┬─────┐
│ Trick │ North │ East │ South (You) │ West │ Winner │ Pts │
├───────┼───────┼──────┼─────────────┼──────┼────────┼─────┤
│ 1-5   │ ...   │ ...  │ ...         │ ...  │ North  │ 0   │
├───────┼───────┼──────┼─────────────┼──────┼────────┼─────┤
│ 6     │ ♦K    │ ♥A   │ ♦5          │ ♦2   │ North  │ 1   │
├───────┼───────┼──────┼─────────────┼──────┼────────┼─────┤
│ 7     │ ♦A    │ ♥K   │ ♦10         │ ♥9   │ North  │ 2   │
├───────┼───────┼──────┼─────────────┼──────┼────────┼─────┤
│ 8     │ ♠A    │ ♠K   │ ♠10         │ ♥8   │ North  │ 1   │
├───────┼───────┼──────┼─────────────┼──────┼────────┼─────┤
│ 9     │ ♥Q    │ ♥5   │ ?           │ ...  │ —      │ —   │
└───────┴───────┴──────┴─────────────┴──────┴────────┴─────┘

Penalties: North: 4 (ALL penalty cards so far) -- MOON THREAT!

Your hand: ♣8 ♣J | ♠J ♠Q | ♥3

Legal plays: ♥3 (forced — only heart)

Our ♥3 can't beat ♥Q, so North wins this too. Moon is looking very real... We'll need to win a trick with hearts in the remaining 4 tricks to block it.

Example: Shoot the Moon

North SHOT THE MOON! They took all 26 penalty points — so everyone else gets 26 instead.

╔═══════════════════════════════════════════════╗
║        🌙 NORTH SHOT THE MOON! 🌙             ║
║  North: 0  East: 26  South: 26  West: 26      ║
╚═══════════════════════════════════════════════╝

That was devastating. North dominated from trick 1 with all those aces and kings. We never had a chance to block — no hearts to win a trick with.

Rules

• 4 players, 13 cards each. Goal: score the fewest points.
• Each Heart = 1 point. Queen of Spades = 13 points.
• Pass 3 cards each round: left, right, across, then no pass (repeating).
• 2 of Clubs leads the first trick. Must follow suit if able.
• Hearts cannot be led until broken (played when unable to follow suit).
• First trick: cannot play Hearts or Queen of Spades unless forced.
• Shoot the Moon: take all 26 penalty points and everyone else gets 26 instead.
• Game ends when any player reaches 100 points. Lowest score wins.

License

MIT