RPG

RPG-MCP is a deterministic, schema-driven world kernel that lets embodied AI agents inhabit a simulated reality with real bodies, constraints, and consequences. It provides the physics, persistence, and execution layer you need to run multi-world, agent-based simulations where LLMs propose intentions and the engine validates and executes them in a safe, reproducible manner.

How to use

You will run RPG-MCP as an MCP server and connect with an MCP client. You can operate multiple worlds, manage embodied entities, and drive simulations by issuing high-level intents (move, attack, cast spell, interact). The engine validates every action against physics and rules, ensuring actions are tool-mediated and deterministic across runs. Use the client to configure worlds, create characters, manage inventories, and observe world state through structured feedback from the server.

Typical usage patterns include: creating a world, spawning characters, advancing the world in fixed steps, and issuing intents for each agent. You can fork worlds for branching timelines, track combat with initiative and death saves, and leverage systems like spellcasting, theft, corpse looting, NPC memory, and an improvisation engine to craft dynamic scenarios. All actions flow through MCP tools, with results observable in full audit logs and world state snapshots.

How to install

Prerequisites: you need Node.js for source builds or you can use stand-alone binaries. Ensure you have a supported shell (bash/zsh on macOS/Linux, PowerShell or CMD on Windows). You also need npm to install dependencies when building from source.

Option 1: Stand-alone binaries (recommended). Download the pre-built binary for your platform and run it directly.

Windows: download the Windows binary and run it with the executable name. The binary is self-contained and does not require Node.js.

macOS: download the macOS binary, make it executable, and run it.

Linux: download the Linux binary, make it executable, and run it.

Option 2: From source. This builds a local MCP server you can run and develop against.

Clone the repository and install dependencies, then build and test.

Commands to run:

git clone https://github.com/Mnehmos/rpg-mcp.git
cd rpg-mcp
npm install
npm run build
npm test

MCP client configuration samples

Configure your MCP client to connect to RPG-MCP using either a prebuilt binary or a local source runtime. Two explicit configurations are shown below.

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

For running from source with Node.js, use the following configuration.

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

Available tools

create_world

Create a new world within a project, establishing a unique worldId and baseline environment.

get_world

Retrieve the state or metadata for a specific world by its ID.

list_worlds

List all worlds under the current project, with IDs and high-level stats.

delete_world

Delete a world and cascade its related data to keep the namespace clean.

generate_world

Procedurally generate a world using Perlin noise or other terrain generation techniques.

get_world_state

Dump the full state of a world for inspection or replay.

get_world_map_overview

Provide a summary of biome distribution and key region statistics.

get_world_tiles

Return the full grid of tiles for a world or region.

get_region_map

Detail a single region within a world, including terrain and points of interest.

apply_map_patch

Apply a domain-specific patch to the world map using a DSL for modifications.

preview_map_patch

Dry-run a map patch to preview changes before applying them.

update_world_environment

Adjust time, weather, and seasonal parameters for a world.

find_valid_poi_location

Terrain-aware placement of points of interest within a region.

suggest_poi_locations

Suggest multiple valid POI locations based on terrain and gameplay goals.

create_character

Create a full D&D-style stat block for a character, including inventories and traits.

get_character

Retrieve character data by ID.

update_character

Update any field on a character block.

list_characters

List all characters in the repository or a specific world.

delete_character

Remove a character from the world or database.

create_item_template

Define item types and templates for in-world objects.

get_item

Get an item template by ID.

list_items

List all item templates.

search_items

Query item templates by name, type, or value.

update_item

Modify an item template.

delete_item

Remove an item template.

give_item

Add an item to a character's inventory.

remove_item

Remove an item from a character's inventory.

transfer_item

Move an item between characters.

use_item

Consume or activate an item.

equip_item

Equip an item into an equipment slot.

unequip_item

Unequip an item back to the character's inventory.

get_inventory

Fetch a basic inventory list for a character.

get_inventory_detailed

Get full item details from a character's inventory.

transfer_currency

Move currency between characters with automatic conversion rules.

create_encounter

Initialize a combat encounter with participants.

get_encounter_state

Check current combat state and HP standings.

load_encounter

Resume a saved combat encounter.

end_encounter

End combat and sync health/damage states.

execute_combat_action

Execute a combat action such as attack, heal, move, or cast spell.

advance_turn

Proceed to the next action in initiative order.

roll_death_save

Roll a D&D 5e death save for a participant.

execute_lair_action

Trigger a legendary creature lair action during encounters.

cast_spell

Cast a known spell with slot consumption and validation.

take_long_rest

Restore all HP and spell slots after a long rest.

take_short_rest

Heal and recover minor resources during a short rest.

steal_item

Record theft with heat tracking and witness data.

check_item_stolen

Check if a given item is currently marked as stolen.

check_stolen_items_on_character

List all stolen items held by a character.

check_item_recognition

NPCs recognize stolen items and react accordingly.

sell_to_fence

Sell stolen goods to fences with pricing and heat considerations.

register_fence

Register an NPC as a fence with buy rates and heat capacity.

report_theft

Report theft to authorities and apply bounty tracking.

advance_heat_decay

Process heat decay over time for theft-related items.

get_fence

Retrieve fence details and reputation.

list_fences

List all fences available in the world.

create_corpse

Create a corpse entity when a creature dies.

get_corpse

Retrieve a corpse by ID.

get_corpse_by_character

Find the corpse associated with a character.

get_corpse_inventory

Inspect items on a corpse.

list_corpses_in_encounter

Show corpses present in a combat encounter.

list_corpses_nearby

Find corpses near a given position.

loot_corpse

Loot a corpse for items.

harvest_corpse

Harvest resources from a corpse.

generate_loot

Generate loot based on a loot table.

create_loot_table

Define a custom loot table.

get_loot_table

Retrieve a loot table by ID.

list_loot_tables

List all loot tables in the system.

advance_corpse_decay

Progress decay state for corpses.

cleanup_corpses

Remove decayed corpses from the world.

get_npc_relationship

Fetch relationship status between characters and NPCs.

update_npc_relationship

Create or modify relationship data.

record_conversation_memory

Store a summary of conversations with NPCs.

get_conversation_history

Retrieve memories of conversations with an NPC.

get_recent_interactions

Show recent interactions across NPCs.

get_npc_context

Provide full context for LLM prompt injection.

interact_socially

Phase-2: conduct spatially aware social interactions.

resolve_improvised_stunt

Resolve Rule of Cool stunts with outcomes.

apply_custom_effect

Apply boons, curses, or transformations to entities.

get_custom_effects

List active improvised effects.

remove_custom_effect

Remove an active effect.

process_effect_triggers

Fire triggers when effects reach conditions.

advance_effect_durations

Tick durations for active effects.

attempt_arcane_synthesis

Attempt dynamic spell creation with synthesis.

get_synthesized_spells

List mastered or synthesized spells.

create_quest

Define a quest with objectives and rewards.

get_quest

Retrieve a single quest by ID.

list_quests

List all quests in the world or campaign.

assign_quest

Assign a quest to a character.

update_objective

Increment progress on a quest objective.

complete_objective

Mark an objective as completed.

complete_quest

Mark an entire quest as complete.

get_quest_log

Fetch the full quest log for a character or party.

create_secret

Create hidden information with reveal conditions.

get_secret

Present DM-only view of a secret.

list_secrets

List all secrets for the current world.

update_secret

Modify secret properties.

delete_secret

Remove a secret from the world.

reveal_secret

Show a secret to players when conditions are met.

check_reveal_conditions

Test if secret reveal conditions are satisfied.

get_secrets_for_context

Format secrets for LLM prompt context.

check_for_leaks

Scan text for accidental secret disclosures.

create_party

Create an adventuring party block.

get_party

Retrieve party details by ID.

list_parties

List all parties in the current world.

update_party

Modify party properties.

delete_party

Remove a party from the world.

add_party_member

Add a character to a party.

remove_party_member

Remove a character from a party.

update_party_member

Change a party member's role or status.

set_party_leader

Set the party leader.

set_active_character

Define the active character for prompts.

get_party_members

Fetch party members with full details.

get_party_context

Get a summary of the party for LLM prompts.

get_unassigned_characters

List characters not currently in a party.

move_party

Move an entire party across the world map.

get_party_position

Show the current party location.

get_parties_in_region

List parties located in a specific region.

look_at_surroundings

Observe current location details.

generate_room_node

Create a room node in the dungeon network.

get_room_exits

List exits from the current room.

move_character_to_room

Move a character between rooms.

dice_roll

Roll dice with full D&D notation (e.g., 2d6+3, 4d6dl1, adv).

probability_calculate

Calculate odds for events or actions.

algebra_solve

Solve algebraic equations.

algebra_simplify

Simplify algebraic expressions.

physics_projectile

Compute projectile trajectories for physics tests.

create_nation

Create a grand strategy nation with resources and headers.

get_nation_state

Retrieve private nation state data.

get_strategy_state

View the world with fog of war and strategic context.

propose_alliance

Suggest diplomatic actions like alliances.

claim_region

Make territorial claims in the world map.

init_turn_state

Initialize turn-based state for strategy play.

get_turn_status

Check readiness of nations for turns.

submit_turn_actions

Submit batch actions for a turn.

mark_ready

Signal that a nation is ready for the turn.

resolve_turn

Process all actions for a turn.

poll_turn_results

Get resolution results for turn actions.