---
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](YOUR_VIDEO_LINK_HERE)** *(Required for submission)*

---

## 🐦 Social Media

> **[🐦 See the announcement on X/Twitter](YOUR_SOCIAL_POST_LINK_HERE)** *(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`:

```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](https://huggingface.co/spaces/MCP-1st-Birthday/murder-mystery)** — Full Gradio UI using this MCP server (Track 2 submission)

---

## 📜 License

MIT