D&D 5e MCP Server for AI Dungeon Masters
A Model Context Protocol (MCP) server providing 30+ D&D 5e tools for LLM-powered tabletop gaming. Features real-time combat tracking, character persistence, ASCII art rendering, and a web client interface.
- 30+ D&D 5e Tools - Character creation, combat encounters, spell tracking, dice rolling
- ASCII Art Output - Retro-style box drawing for immersive terminal/chat display
- Dual Transport - stdio for Claude Desktop, SSE for web client
- Real-time Sync - WebSocket broadcasting for encounter updates
- Persistent Storage - Characters and encounters saved to AppData
- Web Client - Browser-based interface with typing indicators
npm install
npm run build
# Run with stdio (for Claude Desktop)
npm start
# Run with SSE (for web client, port 3001)
node dist/index.js --sseAdd to your Claude Desktop config:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"chatrpg": {
"command": "node",
"args": ["C:\\path\\to\\ChatRPG\\dist\\index.js"]
}
}
}The web client connects to the SSE endpoint:
# Start server with SSE
node dist/index.js --sse
# Open web-client/index.html in browser| Tool | Description |
|---|---|
create_character |
Full D&D 5e character creation with auto-calculated stats |
get_character |
Retrieve by ID/name, supports listing and filtering |
update_character |
Modify stats with before/after comparison |
delete_character |
Remove with cascade cleanup, batch support |
level_up |
Level progression with HP rolls, spell slots |
take_rest |
Short/long rest with hit dice and recovery |
manage_spell_slots |
Full/half/third casters, warlock pact magic |
roll_check |
Skill checks, saves, attacks, initiative |
| Tool | Description |
|---|---|
create_encounter |
Initialize combat with participants and terrain |
get_encounter |
Retrieve state with verbosity levels |
execute_action |
Attack, dash, dodge, disengage, grapple, shove, cast |
advance_turn |
Turn management with condition ticking |
end_encounter |
Close with outcome tracking |
roll_death_save |
D&D 5e death save mechanics |
manage_condition |
Apply/remove conditions with duration |
manage_encounter |
Composite operations with state sync |
render_battlefield |
ASCII tactical map |
modify_terrain |
Hazards, obstacles, difficult terrain |
| Tool | Description |
|---|---|
manage_concentration |
Concentration checks and tracking |
manage_aura |
Spirit Guardians, Paladin auras, etc. |
use_scroll |
Spell scroll mechanics |
synthesize_spell |
Improvised magic with Arcana checks |
| Tool | Description |
|---|---|
measure_distance |
Grid-based distance (5e rules) |
calculate_aoe |
Sphere, cone, line, cube, cylinder |
check_line_of_sight |
Obstacle detection |
check_cover |
Half, three-quarters, full cover |
place_prop |
Interactive battlefield objects |
calculate_movement |
Pathfinding with terrain |
| Tool | Description |
|---|---|
manage_location |
Location graph for navigation |
move_party |
Travel between locations |
manage_party |
Party composition and roles |
manage_inventory |
Item management and equipping |
manage_notes |
Session notes with tagging |
get_session_context |
Comprehensive state snapshot |
| Tool | Description |
|---|---|
roll_dice |
Standard notation, advantage/disadvantage, batch rolls |
ChatRPG/
├── src/
│ ├── index.ts # MCP server (stdio + SSE transports)
│ ├── registry.ts # Tool registration (30+ tools)
│ ├── types.ts # Shared Zod schemas
│ ├── fuzzy-enum.ts # Fuzzy enum matching
│ ├── websocket.ts # Real-time broadcasting
│ └── modules/
│ ├── ascii-art.ts # Box drawing, formatting
│ ├── characters.ts # Character CRUD, leveling
│ ├── combat.ts # Encounters, conditions, actions
│ ├── data.ts # Locations, party, inventory, notes
│ ├── dice.ts # Dice parsing and rolling
│ ├── magic.ts # Spells, concentration, auras
│ └── spatial.ts # Distance, AoE, movement
├── web-client/ # Browser-based interface
├── tests/ # Vitest test suites
├── dist/ # Compiled output
└── design docs/ # ADRs and documentation
# Development with auto-rebuild
npm run dev
# Type check
npx tsc --noEmit
# Build
npm run build
# Run tests
npm test
# Run tests once
npm test -- --run- Define Zod schema in
src/modules/[module].ts - Write handler function
- Export schema from module
- Register in
src/registry.ts - Add tests in
tests/[module]/
- main - Production-ready, auto-deploys to Railway
- development - Active development branch
Character and session data is stored in:
- Windows:
%APPDATA%\rpg-lite-mcp\ - macOS/Linux:
~/.config/rpg-lite-mcp/
rpg-lite-mcp/
├── characters/ # Character JSON files
├── encounters/ # Active encounter state
├── locations/ # Location graph
├── party/ # Party composition
└── notes/ # Session notes
Ask Claude:
"Create a level 5 halfling rogue named Finn with high dexterity"
Response:
╔═══════════════════════ CHARACTER SHEET ════════════════════════╗
║ Finn ║
║ PC - Halfling Rogue (Level 5) ║
║ ║
║ HP: [████████████████] 35/35 ║
║ ║
║ ────────────────────────────────────────────────────────────── ║
║ ║
║ AC │ Speed │ Initiative │ Prof Bonus ║
║ 15 │ 25 ft │ +4 │ +3 ║
╚════════════════════════════════════════════════════════════════╝
Other commands:
- "Roll 4d6 drop lowest for ability scores"
- "Start a combat encounter with 3 goblins"
- "Cast fireball centered at position 5,5"
- "Move the party to the tavern"
The server is deployed on Railway and auto-deploys from the main branch.
SSE Endpoint: https://chatrpg-production.up.railway.app/
- Verify build:
npm run build - Check path in config is absolute
- Test manually:
node dist/index.js
- Rebuild:
npm run build - Run tests:
npm test -- --run - Check TypeScript:
npx tsc --noEmit
If ASCII art displays as garbled text (e.g., ââ€â‚¬ instead of ─), ensure:
- Source files are UTF-8 encoded
- Terminal/client supports Unicode
- No double-encoding in transport layer
- Transports: stdio, SSE (Server-Sent Events)
- Format: JSON-RPC 2.0
- Capabilities: Tools (30+)
- ASCII Art First - All output uses box drawing for terminal aesthetics
- Zod Validation - Strict input schemas with fuzzy enum matching
- Stateful Persistence - JSON files in AppData
- D&D 5e Accurate - SRD-compliant mechanics
- Real-time Updates - WebSocket broadcasting for encounters
This project follows TDD:
- Write failing tests
- Implement minimal code to pass
- Refactor
PRs must:
- Include tests
- Pass TypeScript strict mode
- Follow existing patterns
Proprietary - Personal, non-commercial use permitted. See LICENSE.
- @modelcontextprotocol/sdk - MCP TypeScript SDK
- Zod - Schema validation
- Vitest - Testing framework
- D&D 5e SRD (System Reference Document)
