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