gamebook
This MCP server lets an LLM play and control a choose-your-own-adventure gamebook through session-based tools.
begin_adventure – Start a new adventure session and get the opening scene and choices.
choose_action – Move the story forward by selecting one of the offered action/choice IDs.
use – Use an inventory item or a stateful item in the current scene.
examine – Get a description of an inventory item or an item in the current scene.
look_around – Review the current scene and the items present there.
request_hint – Ask for a subtle hint, or set
directtotruefor a stronger clue.check_player_status – Check the player's current health and inventory.
take_item – Pick up an item and add it to the inventory.
drop_item – Remove an inventory item and leave it in the current place.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gamebook Start a new adventure and show me the opening scene."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Gamebook
A minimal choose-your-own-adventure system with a FastAPI book backend and a Python MCP server that exposes the story to an LLM.
Run it
Play the adventure directly in a terminal. This starts the backend automatically if it is not already running:
uv run gamebook-playSelect a story with --story; the current observatory adventure is the default:
uv run gamebook-play --story observatory
uv run gamebook --story observatory
uv run gamebook-backend --story observatoryEach built-in story is defined in a YAML file under src/gamebook/stories and
registered in gamebook.story.STORY_MODULES.
Related MCP server: LLMMO Game Server
Story YAML
Each story file has a start_scene_id and a scenes mapping. A scene defines
its narrative text, items, optional stateful_items, and outgoing edges.
The loader validates the YAML and converts it into the same NetworkX graph and
runtime models used by the game engine.
start_scene_id: hall
scenes:
hall:
title: Hall
context: A locked door leads into the library.
hint: The door needs a key.
items: []
stateful_items:
- id: library_door
name: Door
is_takeable: false
initial_state: Locked
descriptions:
Locked: The Door is Locked.
Unlocked: The Door is Unlocked.
edges:
- id: library_door
destination_scene_id: library
stateful_item_id: library_door
choice: {id: library, description: Enter the library.}
rule:
required_item_states:
- {item_id: library_door, state: Unlocked}
bidirectional: true
reverse:
choice: {id: hall, description: Return to the hall.}
library:
title: Library
context: Dusty shelves fill the room.
hint: The shelves are worth examining.
items: []State predicates use {item_id, state} mappings. Stateful-item transitions use
{from, to}, and an item-use conditional rule can set states and replace the
item's normal action_message when its required states match.
Use story-level stateful_item_groups for rules that depend on a combination of
stateful items, including items in different scenes. Rules are evaluated in order after a group member changes;
the first matching rule applies its effects and optional action_message.
Stories use a NetworkX MultiDiGraph. Each graph node stores a StoryNode
containing the scene text and items, while each directed edge stores the choice,
visibility conditions, traversal rules, and state changes for moving to another
scene. A multigraph allows multiple distinct choices to connect the same pair of
scenes.
Each StoryNode declares its outgoing StoryEdge values. create_story
validates those declarations and builds the graph, expanding a bidirectional
edge into reciprocal directed edges. The reciprocal edges share one stable edge
ID; when supplied with a non-takeable StatefulItem, its mutable state is stored
once per adventure and is therefore visible from both connected scenes. The
graph remains a shared story template and never stores player session state.
Enter a choice number to move through the story. Other commands include
use <item> [on <target>], examine <item>, take <item>, drop <item>, inventory, look,
hint, hint direct,
restart, and quit.
Set requires_target: true on an item to require the on <target> form.
Start the book backend and Streamable HTTP MCP server together:
uv run gamebookDocker
Build the image and start both the MCP server and backend:
make build
make runThe MCP server is available at http://localhost:8000/mcp; the backend is
available at http://localhost:8001. Set STORY to choose a registered story,
for example make run STORY=observatory.
Start the terminal player in a container with:
make playThe MCP endpoint is http://localhost:8000/mcp. It listens on all WSL network
interfaces so applications running on Windows can connect to it. The backend
listens internally at http://127.0.0.1:8001; its interactive API docs are at
http://127.0.0.1:8001/docs.
Configure LM Studio's mcp.json to connect to the already-running server:
{
"mcpServers": {
"gamebook": {
"url": "http://localhost:8000/mcp"
}
}
}VS Code is configured separately to launch gamebook-mcp over stdio from
.vscode/mcp.json. Open the MCP Servers view or run MCP: List Servers, then
start gamebook to use or debug it. The HTTP backend must also be running for
tools launched this way.
For development, the components can also run separately:
uv run gamebook-backend
uv run gamebook-mcpPoint the MCP bridge at another backend by setting GAMEBOOK_BACKEND_URL.
MCP tools
begin_adventurestarts a session and returns the opening scene.choose_actionsends one of the offered choice IDs to the backend.useuses an inventory item or a stateful item in the current scene.examinedescribes an inventory item or an item in the current scene.look_aroundreturns the current scene and items present there.request_hintasks the backend for a subtle or direct clue.check_inventoryreturns the player's health and inventory.take_itemmoves an item from the current place into the player's inventory.drop_itemmoves an inventory item into the player's current place.
Run the tests with uv run pytest.
Available Tools
9 toolsbegin_adventureB
Begin a new adventure and receive its opening context and choices.
Inputs: adventure_session_id. Returns: title, choices, context, message, +3 more
check_player_statusB
Check the player's current health and inventory.
Inputs: adventure_session_id (required). Returns: health, message, inventory, adventure_session_id
choose_actionC
Choose one of the action IDs offered by the current scene.
Inputs: choice_id (required), adventure_session_id (required). Returns: title, choices, context, message, +3 more
drop_itemC
Drop an inventory item in the player's current place.
Inputs: item_name (required), adventure_session_id (required). Returns: health, message, inventory, adventure_session_id
examineB
Examine an inventory item or an item present in the current scene.
Inputs: item_name (required), adventure_session_id (required). Returns: message, item_name, description
look_aroundB
Review the current place, including any items present there.
Inputs: adventure_session_id (required). Returns: title, choices, context, message, +3 more
request_hintA
Request a subtle hint, or set direct to true for a stronger clue.
Inputs: adventure_session_id (required), direct. Returns: hint, strength, adventure_session_id
take_itemB
Take an item using its exact name; failures list the available item names.
Inputs: item_name (required), adventure_session_id (required). Returns: health, message, inventory, adventure_session_id
useB
Use an inventory item or a stateful item present in the current scene.
Inputs: item_name (required), adventure_session_id (required). Returns: title, choices, context, message, +3 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools map cleanly to distinct actions: starting, choosing, examining, looking, using, taking, dropping, hinting, and checking status. Minor overlap exists between look_around and examine since both inspect the current environment, but their intended purposes remain distinguishable.
The naming pattern is mostly verb_noun with clear action-oriented names like begin_adventure, take_item, and drop_item. The bare verbs 'use' and 'examine' deviate slightly from the pattern, but they are still intuitive and readable.
Nine tools is well-scoped for a gamebook server, covering the core interaction loop without unnecessary bloat. Each tool serves a clear gameplay purpose, and the count feels appropriate for the domain.
The tool set covers the core interactive fiction lifecycle: starting, choosing, looking, examining, using, taking, dropping, hinting, and status tracking. A minor gap is the lack of a dedicated way to refetch the current scene's available actions without beginning or choosing, which could leave agents stuck if context is lost.
Related MCP Connectors
Remote MCP server for AIStoryHub: stories, chapters, story bible, Voiceprints, AI generation.
Free blind-play night-fishing game over MCP. Deterministic engine, zero LLM calls, save codes.
MCP server for AI dialogue using various LLM models via AceDataCloud
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables playing a Workato-themed text-based RPG through MCP tools, allowing users to explore dungeons, battle enemies, and manage character progression in an integration-themed adventure.151MIT
- AlicenseNot gradedqualityDmaintenanceEnables LLM-driven text game state management by exposing MCP tools for managing players, locations, items, entities, and abstract concepts.MIT
- FlicenseAqualityCmaintenanceA text-adventure interpreter as an MCP server. It enables the AI to act as the player, exploring, solving puzzles, fighting trolls, and collecting treasure through tool calls.5-
- AlicenseNot gradedqualityCmaintenanceMCP server that enables AI agents to create, edit, validate, and export single-file HTML text adventure games using JSON story data and MCP tools.10 npmMIT