A rules-enforced RPG backend that turns any LLM into a game master who can't cheat.

You are the player. The AI is the dungeon master.

You talk to an AI (Claude, GPT, etc.) in natural language. You say things like "I attack the goblin" or "I search the room for traps." The AI narrates what happens and describes the world.

The difference from pure AI storytelling: This engine enforces the rules. When you attack, it actually rolls dice, checks armor class, calculates damage, and updates HP in a real database. The AI can't just decide you hit or miss—the math happens, and both you and the AI see the result.

• Explore procedurally generated worlds with 28+ biome types
• Fight enemies using D&D 5e-style combat (initiative, AC, damage rolls, death saves)
• Cast spells with real slot tracking—if you're out of slots, you can't cast
• Manage inventory with equipment slots, weight, and item properties
• Complete quests with tracked objectives and rewards
• Interact with NPCs who remember your conversations across sessions
• Everything persists—close the game, come back tomorrow, your character is exactly where you left them

• Solo RPG players who want AI-driven adventures with mechanical integrity
• People frustrated with AI RPGs that fall apart when you ask "wait, how much HP do I have?"
• Developers building AI game integrations who need a reference implementation

1. Install the MCP server (see Installation below)
2. Connect it to Claude Desktop (or any MCP-compatible client)
3. Tell the AI: "Let's start a new game. Create a character for me."
4. Play naturally—the AI handles narration, the engine handles mechanics

RPG-MCP is a world kernel—the physics, constraints, persistence, and deterministic execution layer that allows LLM agents to inhabit a simulated reality with real bodies, real limits, and real consequences.

• 145+ MCP Tools - Complete RPG mechanics coverage with new composite tools
• 800+ Passing Tests - Comprehensive test coverage across all systems
• Composite Tools (TIER 1) - Reduce token overhead by 80-95% for common workflows
• Preset Systems - 1100+ creature presets, 50+ encounter presets, 30+ location presets
• Schema Shorthand (TIER 2) - Token-efficient position/stats parsing
• Batch Repository Methods - Optimized for world generation workflows
• Location Presets - Tavern, dungeon, temple, market presets with full population
• Encounter Presets - Level-scaled encounters (goblin ambush, undead crypt, dragon's lair)

• Full Spellcasting System - 15+ SRD spells, class progression, slot tracking
• Theft & Fence System - Heat decay, witness tracking, black market economy
• Corpse & Loot System - Decay states, harvestable resources, loot tables
• NPC Memory System - Relationship tracking, conversation history, context injection
• Improvisation Engine - Rule of Cool stunts, custom effects, arcane synthesis
• Legendary Creatures - Lair actions, legendary resistances, boss mechanics
• Death Saving Throws - Full D&D 5e rules with stabilization
• Spatial Navigation - Room networks, terrain-aware POI placement
• Narrative Memory Layer - Session notes, plot threads, NPC voices, foreshadowing
• Currency System - Gold/silver/copper with auto-conversion

This engine implements the Event-Driven Agentic AI Architecture:

┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                                         │
│   EVENT                                                                                 │
│     │                                                                                   │
│     ▼                                                                                   │
│   ┌───────────┐     ┌───────────┐     ┌────────────┐     ┌───────────┐     ┌─────────┐ │
│   │  OBSERVE  │ ──▶ │  ORIENT   │ ──▶ │   DECIDE   │ ──▶ │    ACT    │ ──▶ │VALIDATE │ │
│   │           │     │           │     │            │     │           │     │         │ │
│   │ MCP Read  │     │ LLM Brain │     │Orchestrator│     │ MCP Write │     │ Engine  │ │
│   │  Tools    │     │  Analyze  │     │   Plan     │     │   Tools   │     │  Rules  │ │
│   └───────────┘     └───────────┘     └────────────┘     └───────────┘     └────┬────┘ │
│         ▲                                                                       │      │
│         │                                                                       │      │
│         └───────────────────────────────────────────────────────────────────────┘      │
│                                    WORLD STATE                                         │
│                                  (updates & loops)                                     │
│                                                                                         │
└─────────────────────────────────────────────────────────────────────────────────────────┘

Key invariant: LLMs propose intentions. The engine validates and executes. LLMs never directly mutate world state.

Multi-tenant & Multi-world

• Isolated projects (projectId) and parallel worlds (worldId)
• Fork worlds for branching timelines or "what-if" simulations

Embodied Entities

• Position, velocity, orientation in 3D space
• Stats, inventories, status effects, controller links
• Sensory radius, line-of-sight, perception limits

Intent-Based Actions

• Agents submit intentions: MOVE_TO, ATTACK, CAST_SPELL, INTERACT
• Engine validates against physics, rules, and constraints
• Invalid actions rejected with structured feedback

Deterministic Physics

• Collision detection, projectile trajectories, movement costs
• Reproducible world steps—same inputs always yield same outputs
• Full audit trail: snapshots, event logs, action history

• Initiative tracking with advantage/disadvantage
• Spatial combat with grid positioning and collision
• Opportunity attacks with reaction economy
• Death saving throws (D&D 5e rules)
• Damage resistance/vulnerability/immunity
• Legendary creatures with lair actions and legendary resistances
• Encounter presets - Pre-balanced encounters by party level

• 15+ SRD spells (Magic Missile, Fireball, Cure Wounds, etc.)
• Spell slot tracking with class-based progression
• Warlock pact magic with short rest recovery
• Concentration tracking
• Anti-hallucination validation - LLMs cannot cast spells they don't know
• Rest mechanics restore spell slots and HP

• Stolen item tracking with heat levels (burning → cold)
• Witness recording for theft detection
• Fence NPCs with buy rates and heat capacity
• Item recognition - original owners detect their stolen goods
• Heat decay over time

• Corpse creation on creature death
• Loot tables with guaranteed and random drops
• Harvestable resources (pelts, fangs, etc.)
• Decay system (fresh → decaying → skeletal → gone)

• Relationship tracking (familiarity + disposition)
• Conversation memory with importance levels
• Context injection for LLM prompts
• Interaction history across sessions

• Rule of Cool stunts - "I kick the brazier into the zombies"
• Custom effects - Divine boons, curses, transformations
• Arcane synthesis - Dynamic spell creation with wild surge risk

src/
├── schema/           # Zod schemas: entities, actions, world state, constraints
│   └── base-schemas.ts  # Reusable field definitions for token efficiency
├── engine/
│   ├── combat/       # Encounters, initiative, damage, death saves
│   ├── spatial/      # Grid, collision, movement, opportunity attacks
│   ├── worldgen/     # Procedural generation (28+ biomes)
│   ├── magic/        # Spell database, validation, resolution
│   └── strategy/     # Nation simulation (grand strategy mode)
├── data/
│   ├── creature-presets.ts   # 1100+ creature templates
│   ├── encounter-presets.ts  # 50+ balanced encounters
│   ├── location-presets.ts   # 30+ location templates
│   └── items/               # PHB weapons, armor, magic items
├── storage/
│   ├── migrations.ts # SQLite schema definitions
│   └── repos/        # Repository pattern for persistence
├── server/           # MCP tool handlers
│   ├── composite-tools.ts    # TIER 1: High-level workflow tools
│   ├── combat-tools.ts
│   ├── corpse-tools.ts
│   ├── improvisation-tools.ts
│   ├── inventory-tools.ts
│   ├── npc-memory-tools.ts
│   ├── narrative-tools.ts
│   ├── theft-tools.ts
│   └── ... (20+ tool modules)
├── utils/
│   └── schema-shorthand.ts   # TIER 2: Token-efficient parsing
└── api/              # MCP server entry point

tests/                # 746 tests mirroring src/ structure
docs/                 # White paper and LLM spatial guide

Download the pre-built binary for your platform from the Releases page:

Windows:

# Download rpg-mcp-win.exe
# No Node.js installation required!
.\rpg-mcp-win.exe

macOS (Intel):

# Download rpg-mcp-macos
chmod +x rpg-mcp-macos
./rpg-mcp-macos

macOS (Apple Silicon - M1/M2/M3/M4):

# Download rpg-mcp-macos-arm64
chmod +x rpg-mcp-macos-arm64
./rpg-mcp-macos-arm64

Linux:

# Download rpg-mcp-linux
chmod +x rpg-mcp-linux
./rpg-mcp-linux

The binaries are self-contained and include all dependencies. No Node.js installation needed.

git clone https://github.com/Mnehmos/rpg-mcp.git
cd rpg-mcp
npm install
npm run build
npm test  # 800+ tests should pass

To build binaries yourself:

npm run build:binaries
# Output: bin/rpg-mcp-win.exe, rpg-mcp-macos, rpg-mcp-macos-arm64, rpg-mcp-linux

To use with an MCP-compatible client (Claude Desktop, etc.), add to your client's configuration:

Using Binary:

{
  "mcpServers": {
    "rpg-mcp": {
      "command": "path/to/rpg-mcp-win.exe"
    }
  }
}

Using Source:

{
  "mcpServers": {
    "rpg-mcp": {
      "command": "node",
      "args": [ "path/to/rpg-mcp/src/dist/index.js"]
    }
  }
}

Tabletop RPG Backend Run D&D, Pathfinder, or custom systems with AI dungeon masters and NPCs that have real bodies and spatial reasoning.

Multi-Agent Simulation Test agent coordination, emergent behavior, or adversarial scenarios in a controlled, reproducible environment.

Embodied AI Research Study how LLMs behave when constrained by physics, resources, and perception limits—not just text.

Game Development Use as a headless game server with deterministic state, replay capability, and clean API boundaries.

Training Data Generation Fork worlds, run thousands of parallel scenarios, collect structured action/outcome pairs.

1. LLMs propose, never execute The brain suggests; the nervous system validates.

2. All action is tool-mediated No direct world mutation. Every change flows through MCP tools.

3. Validation precedes observation Act → Validate → Observe. The reflex arc pattern.

4. Events trigger tasks JIT execution. No polling, no stale state.

5. Deterministic outcomes Same inputs → same outputs. Always reproducible.

6. Schema-driven everything Zod validates all data at boundaries. Type safety end-to-end.

7. Anti-hallucination by design LLMs cannot cast spells they don't know or claim damage they didn't roll.

8. Token efficiency Composite tools and schema shorthand reduce LLM context overhead.

npm test
# 800+ tests passing
# 90+ test files
# Coverage across all major systems

Key test areas:

• Combat encounters and HP persistence
• Spellcasting validation (anti-hallucination)
• Inventory integrity and exploit prevention
• Theft/fence mechanics with heat decay
• Corpse/loot system with decay states
• NPC memory and relationship tracking
• Improvisation system (stunts, effects, synthesis)
• Composite tool workflows
• Preset system expansion and validation

Contributions welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/your-feature)
3. Write tests for new functionality
4. Follow existing code style (TypeScript + Zod + tests)
5. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

• Full spellcasting system with validation
• Theft and fence economy
• Corpse and loot mechanics
• NPC memory and relationships
• Improvisation engine
• Composite tools (TIER 1)
• Preset systems (creatures, encounters, locations)
• Narrative memory layer
• WebSocket real-time subscriptions
• Dialogue tree system
• Cover mechanics in combat
• Quest chains with prerequisites
• Visual debugger / world inspector UI

ISC — Use freely, attribution appreciated.

• Model Context Protocol Specification
• Quest Keeper AI — Desktop AI dungeon master using this engine

• CLAUDE.md - Development instructions
• docs/WHITE_PAPER.md - Design philosophy and architecture
• docs/LLMSpatialGuide.md - LLM spatial navigation guide

"AI-native autonomic organisms capable of maintaining and improving themselves in complex environments"