Ttrpg MCP On Cloudflare
My attempt to do an MCP server with GitHub Pages
Installation
npx ttrpg-mcp-on-cloudflareAsk AI about Ttrpg MCP On Cloudflare
Powered by Claude Β· Grounded in docs
I know everything about Ttrpg MCP On Cloudflare. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
TTRPG GM Tools MCP Server
A Model Context Protocol server for tabletop RPG game masters.
ποΈ Architecture
This project uses a two-part architecture:
- GitHub Pages - Hosts static data files (encounters, names, treasures, etc.) at
https://ttrpg-mcp.tedt.org/ - Cloudflare Worker - Implements the MCP protocol and executes tool logic at
https://ttrpg-mcp.tedt.org/mcp
Note: GitHub Pages can only serve static files. The MCP protocol requires a real server to handle dynamic requests, which is why we need the Cloudflare Worker.
π² Features
This MCP server provides tools for game masters:
- Random Encounter Generator - Generate random encounters based on difficulty and environment
- NPC Name Generator - Create character names for various fantasy races
- Location Name Generator - Generate tavern, city, and dungeon names
- Personality Trait Generator - Create NPC personalities and quirks
- Treasure Generator - Generate loot and treasure hoards
- Weather Generator - Create atmospheric weather descriptions
- Plot Hook Generator - Generate adventure hooks and quest ideas
π§ Setup
Prerequisites
- Deploy the Cloudflare Worker (see
cloudflare-mcp-server/README.md) - Configure your MCP client
For MCP Clients (Claude Desktop, etc.)
Add this to your MCP client configuration:
{
"mcpServers": {
"ttrpg-gm-tools": {
"url": "https://ttrpg-mcp.tedt.org/mcp",
"transport": {
"type": "http"
}
}
}
}
Important:
- The URL is
https://ttrpg-mcp.tedt.org/mcp(notmcp.json) - Transport is Streamable HTTP (JSON responses), not SSE
- You must deploy the Cloudflare Worker first (see
cloudflare-mcp-server/folder)
Local Development
- Clone this repository
- Install Ruby 3.1+ (system Ruby 2.6/2.7 is often too old for
github-pages) - Install Bundler (if needed):
gem install bundler - Install site dependencies:
bundle install - Run locally (from the repo root):
bundle exec jekyll serve - Visit:
http://localhost:4000/
π Structure
βββ _config.yml # Jekyll configuration
βββ data/ # JSON data files for generators
β βββ encounters.json # Encounter data
β βββ names.json # NPC names by race
β βββ locations.json # Location names
β βββ traits.json # Personality traits
β βββ treasure.json # Treasure tables
β βββ weather.json # Weather descriptions
β βββ plot_hooks.json # Adventure hooks
βββ cloudflare-mcp-server/ # Cloudflare Worker implementation
β βββ src/index.ts # Worker entrypoint (/mcp)
β βββ src/mcp/server.ts # MCP SDK server registration (tools/resources/prompts)
β βββ src/tools/ # Central registry + per-tool modules
β βββ src/data/fetch.ts # JSON fetch + Cloudflare caching
β βββ test/ # Vitest smoke tests
βββ demo.md # Interactive demo page
βββ index.md # Landing page
π Usage
Once configured in your MCP client, you can use natural language to invoke tools:
- "Generate a random encounter for a level 5 party in a forest"
- "Give me a dwarf name for my NPC"
- "Create a tavern name"
- "Generate some personality traits for my villain"
π οΈ Technology Stack
- Jekyll/Liquid - Static site generation
- GitHub Pages - Hosting
- JSON - Data storage and API responses
- MCP SDK - MCP server implementation (
@modelcontextprotocol/sdk)
βοΈ Runtime Behavior
/mcpacceptsPOSTonly;GET /mcpreturns405- CORS is restricted via
ALLOWED_ORIGINS(missingOriginis allowed for non-browser clients) - Data reads are cached (in-memory + Cloudflare Cache API)
- The server supports
completion/completefor prompt args and for the resource template variable inttrpg://data/{dataset} - Tool results and prompt messages may include
resource_linkcontent blocks pointing at related datasets - The server and dataset resources include MCP
iconsmetadata (light/dark SVGs)
π License
MIT License - Feel free to use and modify for your campaigns!
π€ Contributing
Contributions welcome! Add more:
- Encounter types
- Name lists for different cultures/races
- Treasure items
- Plot hooks
- New tool types
