---

title: Murder Mystery MCP Server emoji: 🕵️ colorFrom: indigo colorTo: red sdk: gradio sdk_version: "5.29.1" app_file: demo.py pinned: false tags:

• building-mcp-track-creative
• mcp
• mcp-server
• game-engine
• murder-mystery
• agents
• tools
• resources

---

🕵️ Murder Mystery MCP Server

🎉 MCP 1st Birthday Hackathon — Track 1: Building MCP (building-mcp-track-creative)

A complete murder mystery game engine exposed as a Model Context Protocol (MCP) server. Generate procedural mysteries, interrogate AI suspects, search for clues, and solve crimes — all through MCP tools that any AI agent can use.

---

📺 Demo Video

👉 Watch the Demo Video (Required for submission)

---

🐦 Social Media

🐦 See the announcement on X/Twitter (Required for submission)

---

👥 Team

HuggingFace Username
@YOUR_HF_USERNAME

---

🚀 Quick Start

Use with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "murder-mystery": {
      "command": "python",
      "args": ["-m", "murder_mystery_mcp"],
      "cwd": "/path/to/murder-mystery-mcp",
      "env": {
        "OPENAI_API_KEY": "your-key",
        "HF_TOKEN": "your-hf-token",
        "ELEVENLABS_API_KEY": "your-elevenlabs-key"
      }
    }
  }
}

Then just chat with Claude:

• "Start a new murder mystery game"
• "Talk to the butler about his alibi"
• "Search the library for clues"
• "I accuse Lady Ashworth of the murder!"

Use with Cursor

Add the same config to Cursor's MCP settings and use the tools in your AI chat.

---

🛠️ MCP Tools

Game Flow Tools

Tool	Description
start_game	Start a new procedurally-generated murder mystery
get_game_state	Get current game state (suspects, clues, progress)
interrogate_suspect	Question a suspect (they have memory + emotions!)
search_location	Search a location for clues
make_accusation	Formally accuse someone of the murder

Investigation Tools (RAG-Powered)

Tool	Description
search_memory	Search all past conversations for relevant statements
find_contradictions	Check if a suspect's story contradicts past statements
get_cross_references	Find what OTHER suspects said about someone
get_investigation_hint	Get a hint if you're stuck
get_timeline	See the investigation timeline

Image Generation Tools

Tool	Description
generate_portrait	Generate a suspect's portrait
generate_scene	Generate a location/scene image
generate_title_card	Generate the mystery's opening scene

---

📚 MCP Resources

URI	Description
mystery://state	Current game state (JSON)
mystery://suspects	List of suspects with public info
mystery://clues	Discovered clues
mystery://timeline	Investigation timeline
mystery://locations	Available and searched locations

---

🎮 How It Works

1. Mystery Generation

When you start a game, the server generates:

• A unique victim with background story
• 4-5 suspects with personalities, secrets, and alibis
• One guilty suspect (the AI won't tell you who!)
• Clues scattered across locations
• An "encounter graph" showing who was really where

2. The Oracle Pattern

The MCP server uses a secure "Oracle" architecture:

• The Mystery Oracle knows the truth (who's guilty, all secrets)
• The tools only return what the player should see
• Even the AI using the tools can't "cheat" — it discovers the truth through gameplay

3. Suspect Emotions

Suspects aren't static — they have:

• Trust (0-100%): How much they trust the detective
• Nervousness (0-100%): How anxious they are
• Memory: They remember past conversations and stay consistent
• Reveals: High trust → reveal locations; high pressure → reveal secrets

4. RAG Memory

All conversations are indexed in a vector store:

• Search for what was said about any topic
• Detect contradictions in testimony
• Cross-reference what suspects said about each other

---

🏗️ Architecture

┌──────────────────────────────────────────────────────────────────┐
│                   MURDER MYSTERY MCP SERVER                       │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  TOOLS (what agents can call):                                    │
│  ├─ start_game          - Generate new mystery                    │
│  ├─ interrogate_suspect - Talk to suspects                        │
│  ├─ search_location     - Find clues                              │
│  ├─ make_accusation     - Accuse the murderer                     │
│  ├─ search_memory       - RAG search past statements              │
│  ├─ find_contradictions - Detect lies                             │
│  ├─ get_cross_references- What others said about someone          │
│  ├─ generate_portrait   - Create character art                    │
│  └─ generate_scene      - Create location art                     │
│                                                                   │
│  RESOURCES (what agents can read):                                │
│  ├─ mystery://state     - Full game state                         │
│  ├─ mystery://suspects  - Suspect list                            │
│  ├─ mystery://clues     - Discovered clues                        │
│  └─ mystery://timeline  - Investigation timeline                  │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    MYSTERY ORACLE (truth)                    │ │
│  │  • Knows who the murderer is                                │ │
│  │  • Knows all suspects' secrets                              │ │
│  │  • Validates accusations                                    │ │
│  │  • Generates consistent suspect responses                   │ │
│  │  • NEVER exposes truth to the agent directly               │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    RAG MEMORY (partitioned)                  │ │
│  │  • Per-suspect conversation history                         │ │
│  │  • Semantic search across all statements                    │ │
│  │  • Contradiction detection                                  │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘

---

⚙️ Configuration

Environment Variable	Required	Description
OPENAI_API_KEY	Yes	For mystery generation and LLM responses
HF_TOKEN	No	For image generation (optional)
ELEVENLABS_API_KEY	No	For voice synthesis (optional, used by UI)

---

🎯 Game Rules

• 3 wrong accusations = Game Over (you're fired from the case)
• Win: Correctly identify the murderer with evidence
• Suspects won't reveal secrets easily — build trust or apply pressure!
• Clues are hidden in locations — search everywhere
• Cross-reference testimony to find contradictions

---

🔗 Related Projects

• Murder Mystery Detective Game — Full Gradio UI using this MCP server (Track 2 submission)

---

📜 License

MIT