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

🚀 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

Investigation Tools (RAG-Powered)

Image Generation Tools

📚 MCP Resources

🎮 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

🎯 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