LLMMO Game Server

MCP server for LLM-driven text game state management. Exposes tools for managing players, locations, items, entities, and abstract concepts via the MCP protocol.

Built with FastAPI, FastMCP, Python 3.14.

Setup

Docker (recommended)

cp .env.example .env  # adjust if needed
docker compose up --build app

Local

uv sync
uvicorn llmmo.main:app --reload --host 0.0.0.0 --port 8111

Configuration

Environment variables (.env):

Variable	Default	Description
BACKEND__RUN__HOST	localhost	Server host
BACKEND__RUN__PORT	8111	Server port
BACKEND__DB__BASE_PATH	.state	Game state storage directory
BACKEND__CORS__ORIGINS	["http://localhost:8111"]	Allowed CORS origins
BACKEND__CORS__CREDENTIALS	true	Allow credentials
BACKEND__CORS__METHODS	["*"]	Allowed HTTP methods
BACKEND__CORS__HEADERS	["*"]	Allowed headers

Authentication

1. Register at GET /register or POST /register
2. Get an API key via POST /auth/api-keys (JSON: {"username": "...", "password": "..."})
3. Use the key as a Bearer token for MCP endpoints: Authorization: Bearer <api_key>

Each user gets isolated game state stored in .state/<username_hash>/.

MCP Endpoint

MCP server is mounted at /mcp. Connect your MCP client to http://localhost:8111/mcp.

Data Model

• Player — name, inventory (item_id -> quantity), current location
• Location — name, description
• Item — name, description (global, referenced by players)
• Entity — name, description, optional location (NPCs, objects, monsters)
• Abstract — name, description (events, topics, lore — not tied to locations)

All IDs are UUIDs. State is persisted as JSON files per user.

Development

uv sync --all-groups  # install dev deps

Before commit: ruff (lint/format), mypy (type check).