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)

🐦 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

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

📜 License

MIT