---
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
