ttrpg-mcp-on-cloudflare

TedTschopp/ttrpg-mcp-on-cloudflare

3.2

If you are the rightful owner of ttrpg-mcp-on-cloudflare and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol server for tabletop RPG game masters, hosted on GitHub Pages using static JSON files and Jekyll.

TTRPG GM Tools MCP Server

A Model Context Protocol server for tabletop RPG game masters.

🏗️ Architecture

This project uses a two-part architecture:

  1. GitHub Pages - Hosts static data files (encounters, names, treasures, etc.) at https://ttrpg-mcp.tedt.org/
  2. 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

  1. Deploy the Cloudflare Worker (see cloudflare-mcp-server/README.md)
  2. 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 (not mcp.json)
  • Transport is Streamable HTTP (JSON responses), not SSE
  • You must deploy the Cloudflare Worker first (see cloudflare-mcp-server/ folder)

Local Development

  1. Clone this repository
  2. Install Ruby 3.1+ (system Ruby 2.6/2.7 is often too old for github-pages)
  3. Install Bundler (if needed): gem install bundler
  4. Install site dependencies: bundle install
  5. Run locally (from the repo root): bundle exec jekyll serve
  6. 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

  • /mcp accepts POST only; GET /mcp returns 405
  • CORS is restricted via ALLOWED_ORIGINS (missing Origin is allowed for non-browser clients)
  • Data reads are cached (in-memory + Cloudflare Cache API)
  • The server supports completion/complete for prompt args and for the resource template variable in ttrpg://data/{dataset}
  • Tool results and prompt messages may include resource_link content blocks pointing at related datasets
  • The server and dataset resources include MCP icons metadata (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

🔗 Resources