What can you do with this server?

ChatRPG is a comprehensive D\&D 5e MCP server providing AI Dungeon Masters with 30+ tools for tabletop gaming, featuring character persistence, real-time combat tracking, ASCII art rendering, and a web client interface. Character Management: Create, update, delete, and level up characters with full D\&D 5e stats, classes, races, equipment, and spell slots. Supports rest mechanics (short/long with hit dice spending), skill checks, saving throws, attack rolls, and spell slot management for all caster types including warlock pact magic. Combat System: Initialize tactical encounters with initiative tracking, terrain, and lighting. Execute actions (attack, dash, dodge, cast spells, grapple, shove) with automatic hit/damage resolution. Manage turn advancement with automatic condition duration tracking, death saves, dynamic terrain modification, cover detection, and ASCII battlefield rendering. Magic System: Track spell concentration with automatic DC calculation, manage aura effects (Spirit Guardians, Paladin auras), use spell scrolls with success/failure resolution, and enable improvised magic through arcane synthesis with Arcana checks. Spatial Mechanics: Calculate grid-based distances with elevation, determine areas of effect (sphere, cone, line, cube, cylinder) with automatic target detection, check line of sight with obstacle detection and special vision modes, calculate movement paths considering terrain, and place interactive props (barrels, doors, chests) with cover, HP, AC, locks, and traps. World & Session Management: Create location graphs with interconnected areas, move the party between locations with locked/hidden passage mechanics, manage party composition with role assignments, handle inventory operations (give/take/equip/transfer), maintain searchable session notes with tags and importance levels, and retrieve comprehensive session context snapshots. Dice Rolling: Supports standard notation (2d6+4, 4d6kh3) with advantage/disadvantage and batch rolling for simultaneous expressions. Technical Features: Persistent storage in AppData/config directories, WebSocket broadcasting for real-time encounter updates, dual transport support (stdio for Claude Desktop, SSE for web clients), fuzzy enum matching for forgiving input parsing, and D\&D 5e SRD-compliant mechanics.

How do I use ChatRPG?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ChatRPG roll a perception check for my rogue Finn" 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.

ChatRPG

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.

Build TypeScript License

Features

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

Quick Start

1. Build & Run

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 --sse

2. Configure Claude Desktop

Add 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"] } } }

3. Web Client

The web client connects to the SSE endpoint:

# Start server with SSE node dist/index.js --sse # Open web-client/index.html in browser

Available Tools

Character Management

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

Combat System

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

Magic System

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

Spatial Mechanics

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

World & Session

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

Dice

Tool	Description
`roll_dice`	Standard notation, advantage/disadvantage, batch rolls

Project Structure

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

Commands

# 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

Adding a New Tool

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]/

Git Workflow

main - Production-ready, auto-deploys to Railway
development - Active development branch

Data Storage

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

Example Usage

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"

Deployment

The server is deployed on Railway and auto-deploys from the main branch.

SSE Endpoint: https://chatrpg-production.up.railway.app/

Troubleshooting

Server Won't Start

Verify build: npm run build
Check path in config is absolute
Test manually: node dist/index.js

Tool Calls Failing

Rebuild: npm run build
Run tests: npm test -- --run
Check TypeScript: npx tsc --noEmit

Encoding Issues

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

Architecture

MCP Protocol

Transports: stdio, SSE (Server-Sent Events)
Format: JSON-RPC 2.0
Capabilities: Tools (30+)

Design Principles

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

Contributing

This project follows TDD:

Write failing tests
Implement minimal code to pass
Refactor

PRs must:

Include tests
Pass TypeScript strict mode
Follow existing patterns

License

Proprietary - Personal, non-commercial use permitted. See LICENSE.

Credits

@modelcontextprotocol/sdk - MCP TypeScript SDK
Zod - Schema validation
Vitest - Testing framework
D&D 5e SRD (System Reference Document)

ChatRPG

ChatRPG

Features

Quick Start

1. Build & Run

2. Configure Claude Desktop

3. Web Client

Available Tools

Character Management

Combat System

Magic System

Spatial Mechanics

World & Session

Dice

Project Structure

Development

Commands

Adding a New Tool

Git Workflow

Data Storage

Example Usage

Deployment

Troubleshooting

Server Won't Start

Tool Calls Failing

Encoding Issues

Architecture

MCP Protocol

Design Principles

Contributing

License

Credits

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API