metadata

title: LLM Game Master MCP Server
emoji: 🧙🏼‍♂️
colorFrom: indigo
colorTo: yellow
sdk: gradio
sdk_version: 5.32.1
app_file: app.py
pinned: true
tags:
  - agent-demo-track
  - mcp-server-track

🧙‍♂️ LLM Game Master MCP Server 🐉

Made by: @Agamador @Javier-Jimenez99

🎥 Video Demo

<iframe width="560" height="315" src="https://www.youtube.com/embed/SlbW-kjekBg?si=r6x8GeVnKLipriZL" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

Video Demo: https://www.youtube.com/watch?v=SlbW-kjekBg&ab_channel=AlejandroGarcíaAmador

🧩 Complete Architecture Overview

Try it out live

We are working to simplify this process, but for now you can try the demo by following these steps:

1. Create an empty room in OwlBear Rodeo

To create a new room in OwlBear Rodeo you need to go to you profile and click on "Create a new room".

2. Create a new scene

Now you need to create a new scene. You can do this by clicking on the "Assets manager" button and adding a new scene. It is recommended to use an empty scene.

3. Add the extension

First you need to go to the "Extensions" tab and click on "Add extension".

Then you need to paste the URL of the extension: https://144.24.204.95:5173/manifest.json.

Finally, you need to click on "Add" button and activate it.

4. Lets play!

Finally the extension is ready to use. Just click on the left up corner button to open the chat interface and start playing.

5. (Optional) Revoke GM privileges

It is recommended to revoke GM privileges to yoour own user to enjoy a more immersive experience. You can do this by going to the "Players" tab and clicking on the "Revoke GM" button on your player.

⚠️ Warning: You need an Anthropic API key to use the chat interface.

🔗 Useful Links:

🌟 Introduction

The OwlBear Rodeo MCP Server is a revolutionary Model Context Protocol (MCP) server implementation that bridges the gap between AI agents and tabletop gaming experiences. This sophisticated system transforms the popular OwlBear Rodeo virtual tabletop platform into a fully programmable environment, enabling AI Game Masters to create, manipulate, and orchestrate dynamic D&D sessions with unprecedented precision and creativity.

Built using Gradio's cutting-edge MCP server capabilities, this application showcases the power of combining modern AI infrastructure with traditional gaming platforms. The server exposes a comprehensive suite of tools that allow AI agents to interact with virtual tabletops in real-time, creating immersive gaming experiences that adapt dynamically to player actions and narrative requirements.

Unlike static gaming interfaces, this MCP server provides AI agents with the ability to programmatically control every aspect of the virtual tabletop experience, from token placement and movement to map management and atmospheric effects like fog of war and lighting systems.

🎯 Core Functionality

🗺️ Dynamic Map Management

The server provides powerful map manipulation capabilities that allow AI agents to create diverse gaming environments on demand. Through the integrated map system, agents can instantly deploy various pre-configured environments including mystical forests with winding paths, quaint villages with detailed buildings, isolated cabin settings, and epic battle arenas designed for climactic encounters.

The map insertion system works seamlessly with OwlBear Rodeo's rendering engine, ensuring that each environment is properly scaled and optimized for tactical gameplay. Maps can be swapped dynamically during sessions, allowing for seamless transitions between different scenes and locations as the narrative unfolds.

🎭 Intelligent Token System

The token creation and management system represents one of the most sophisticated aspects of the MCP server. AI agents can spawn a diverse array of characters and objects, from heroic knights and mystical archers to fearsome dragons and cunning goblins. Each token type corresponds to carefully selected visual assets that enhance the immersive experience.

The system supports dynamic token properties including customizable sizes, precise positioning using grid-based coordinates, and intelligent naming conventions that help track multiple entities throughout complex encounters. Tokens can be moved programmatically, allowing AI Game Masters to orchestrate tactical movements, dramatic reveals, and coordinated battle sequences.

🌫️ Advanced Fog of War

The fog of war implementation provides AI agents with sophisticated tools for controlling information flow and creating suspenseful gaming moments. The system can instantly fill entire maps with fog, creating mysterious environments where only illuminated areas remain visible to players.

The clear fog functionality allows for dramatic reveals, while the selective fog management enables AI Game Masters to control exactly what players can see at any given moment. This creates opportunities for strategic gameplay and narrative tension that rivals traditional tabletop experiences.

💡 Dynamic Lighting System

The lighting system adds another layer of tactical depth and atmospheric immersion to gaming sessions. AI agents can attach light sources to any token, creating realistic illumination effects that interact with the fog of war system. Torches, magical auras, and character-based light sources can be programmatically managed to enhance both gameplay mechanics and visual storytelling.

Light sources move automatically with their attached tokens, ensuring that the lighting environment remains consistent as characters navigate through the virtual space. This feature is particularly powerful for creating tension in dungeon exploration scenarios or highlighting important story elements.

🔧 Utility Tools Integration

Beyond the OwlBear Rodeo specific features, the MCP server includes a comprehensive suite of utility tools that enhance AI agent capabilities. These include mathematical functions for dice rolling simulations, coin flip mechanics for random decision making, prime factorization for complex calculations, and text analysis tools for processing player input.

These utility functions demonstrate the extensibility of the MCP architecture, showing how specialized gaming tools can be combined with general-purpose utilities to create a comprehensive AI assistant platform.

🛠️ MCP Tools Reference

This section provides the complete technical reference for all tools available through the Model Context Protocol server. Each tool is documented with its exact function name, required parameters, and expected behavior to facilitate seamless integration with MCP clients.

🎲 General Utility Tools

The server includes essential utility tools that provide mathematical and randomization capabilities commonly needed in gaming scenarios. These tools demonstrate the extensibility of the MCP architecture and can be used independently or in conjunction with the OwlBear Rodeo specific functionality.

letter_counter

Parameters: word (string), letter (string)
Description: Counts occurrences of a specific letter within any text string
Use case: Text analysis and word games integration

prime_factors

Parameters: n (integer, must be > 1)
Description: Computes the complete prime factorization of any positive integer
Use case: Mathematical puzzles and complex calculations

roll_dice

Parameters: faces (integer), rolls (integer)
Description: Simulates dice rolling with customizable faces and number of rolls
Use case: Random number generation for game mechanics

coin_flip

Parameters: flips (integer)
Description: Simulates multiple coin flips returning "Heads" or "Tails" results
Use case: Binary random decisions and probability demonstrations

🗺️ OwlBear Rodeo Map Management

The map management system provides comprehensive control over virtual tabletop environments, enabling dynamic scene transitions and environmental storytelling through programmatic map manipulation.

insert_map

Parameters: tab_id (string), map_type (string)
Description: Inserts pre-configured map environments into the gaming session
Available map types: FOREST, VILLAGE, LONELY_CABIN, BATTLE_ARENA, CABIN
Use case: Setting scenes and creating immersive environments

clean_map

Parameters: tab_id (string)
Description: Removes all tokens, shapes, and objects from the current map
Use case: Resetting the playing field for new encounters

🎭 Token and Character Management

The token system provides sophisticated character and object management capabilities, allowing AI Game Masters to populate virtual spaces with interactive entities that enhance storytelling and tactical gameplay.

create_token

Parameters: name (string), type (string), x (integer), y (integer), size (integer), tab_id (string)
Description: Creates character or item tokens with specified visual assets
Available token types: BOOK, CHEST, SWORD, TORCH, ARCHER, HUMAN, WOMAN, CHILD, ORC, KNIGHT, DRAGON, GOBLIN, GOLEM
Use case: Populating scenes with characters, items, and interactive objects

move_item

Parameters: tab_id (string), item_id (string), x (integer), y (integer)
Description: Moves any existing token or shape to new grid coordinates
Use case: Orchestrating movement during combat or narrative sequences

delete_item

Parameters: tab_id (string), item_id (string)
Description: Permanently removes a specific token or shape from the map
Use case: Cleaning up defeated enemies or consumed items

🎨 Shape and Visual Elements

The shape creation system enables the addition of geometric elements that can serve as terrain features, area markers, or visual indicators to enhance tactical understanding and environmental storytelling.

create_shape

Parameters: width (integer), height (integer), x (integer), y (integer), shape_type (string), fill_color (hex string), stroke_color (hex string), tab_id (string)
Description: Creates geometric shapes with customizable appearance and positioning
Available shape types: RECTANGLE, CIRCLE, TRIANGLE, HEXAGON
Use case: Creating terrain features, spell areas, or visual markers

🌫️ Fog of War and Visibility Control

The fog of war system provides sophisticated visibility management tools that enable AI Game Masters to control information flow and create suspenseful moments through strategic revelation of map areas.

fill_fog

Parameters: tab_id (string)
Description: Covers the entire map with fog of war, hiding all areas from player view
Use case: Creating mystery and controlling information revelation

clear_fog

Parameters: tab_id (string)
Description: Removes all fog of war from the map, revealing the complete environment
Use case: Dramatic reveals and full area illumination

💡 Lighting and Atmosphere

The lighting system adds tactical depth and atmospheric immersion by providing programmable light sources that interact dynamically with the fog of war system to create realistic illumination effects.

add_token_light

Parameters: tab_id (string), item_id (string), light_radius (integer)
Description: Attaches a light source to any token with specified illumination radius
Use case: Creating torch effects, magical auras, or character-based lighting

🎥 Camera and Viewport Control

The viewport management system enables cinematic control over player perspective, allowing AI Game Masters to direct attention and create dramatic focus during key narrative moments.

animate_token_viewport

Parameters: tab_id (string), item_id (string)
Description: Smoothly animates the camera to focus on a specific token
Use case: Directing player attention during important events

📊 State Management

The state management tool provides essential functionality for monitoring and retrieving the current status of all elements within the virtual tabletop environment.

game_state

Parameters: tab_id (string)
Description: Returns complete current state including all tokens, shapes, and map information
Use case: Monitoring session status and making informed decisions

🔧 Testing and Demonstration

test_function

Parameters: tab_id (string)
Description: Executes a comprehensive demonstration of all OwlBear Rodeo functionality
Use case: System validation and feature showcase

All tools require a tab_id parameter that identifies the specific OwlBear Rodeo session. Coordinates are specified in grid cells, with the origin (0,0) typically located at the top-left corner of the map. Colors must be specified in hexadecimal format (e.g., "#FF0000" for red).

🔗 Links & Resources

Model Context Protocol (MCP) - The foundational protocol enabling AI agent tool integration
Gradio Documentation - The web framework powering the user interface and MCP server implementation
OwlBear Rodeo - The virtual tabletop platform integrated through this MCP server
MCP Server Documentation - Comprehensive guides for MCP server development and deployment