@candlelightgames/mcp
v0.14.0
Published
A local MCP server for Candlelight: the vocabulary for your AI to read, and tools to generate, validate and import campaigns and library content
Maintainers
Readme
@candlelightgames/mcp
An MCP server for Candlelight, a home for tabletop RPG campaigns. It lets an AI client you already use (Claude Desktop, Claude Code, or any other local MCP client) write campaigns and library content with you, and import them into your Candlelight account.
Candlelight has no AI of its own: the model is yours. This server gives it the vocabulary to read, a way to check its work on your machine, and a way to save it. Everything it writes goes through the same import as a file you upload, and you get a draft you can edit like any other.
Documentation: developer.candle-light.games/docs/mcp
Install
It runs on your machine, over stdio, with Node 26.13.0 or later.
Claude Code:
claude mcp add candlelight -- npx -y @candlelightgames/mcpClaude Desktop, in claude_desktop_config.json:
{
"mcpServers": {
"candlelight": {
"command": "npx",
"args": ["-y", "@candlelightgames/mcp"]
}
}
}Claude Code asks before each tool call. The read-only ones can be allowed up front, in
.claude/settings.json:
{
"permissions": {
"allow": [
"mcp__candlelight__reference",
"mcp__candlelight__validate",
"mcp__candlelight__import_preview",
"mcp__candlelight__get"
]
}
}Sign in
Ask your AI to sign in to Candlelight (the sign_in tool), or sign in from a terminal:
npx -y @candlelightgames/mcp loginEither way you get a link to approve in your browser. The sign-in is kept in
~/.config/candlelight/ (readable only by you). logout revokes it, and status says whether
you're signed in.
| Variable | What |
| -------------------------------------------------------------------- | ------------------------------------------- |
| CANDLELIGHT_ENV | production (the default), test, local |
| CANDLELIGHT_API_URL, CANDLELIGHT_AUTH_URL, CANDLELIGHT_WEB_URL | Override one host |
Tools
sign_in,sign_out: sign in to your account, or out.reference: the authoring guide, the vocabulary, shapes and worked examples.validate: checks a document on your machine (syntax and shapes). Sends nothing.import_preview: a dry run of the import: what it would create, and what it can't keep yet.import: imports into your account: a new campaign, into a campaign, or your library.generate: runs one of Candlelight's generators (towns, NPCs, loot, …), saving nothing.get: reads your content, as JSON or exported as Turtle or JSON-LD.create_character,check_character,join_campaign,add_character: for a player making their character: makes it on its system's rules a choice at a time, checks it against them, joins a campaign with an invite, and adds the character to it (themake_characterprompt walks through it all).character_sheet: reads a character's sheet as the app shows it, lists a campaign's characters, and exports them as Open Character Format files for other apps.read_character_sheet: reads a character sheet PDF (D&D Beyond's, the official 2014 or 2024 sheet, Demiplane's Pathfinder 2e, Starfinder 2e or Daggerheart sheet) on your machine, for the campaign document. The file never leaves your machine.generate_one_shot: makes a one-shot (a town, a quest and a dungeon, or a run in a city) with Candlelight's generator and saves it as a new campaign, built to be played with no GM. Read it back withget(Turtle), then add to it withimportin merge mode.upload_image: uploads your own art (a battlemap, a token, a handout) and gives back its URL for the document.upload_link: a signed link to upload a file yourself (curl), so neither art nor a long document passes through the conversation; tools then take the uploaded document by name.draw_town_map,town_map_svg: draws a town's map on your machine, and saves it or writes it out as an SVG.
The author_campaign prompt starts a campaign from a premise.
Licence
MIT. The worked examples it carries (the What the River Owes campaign and a library pack) are
CC BY 4.0. See LICENSE.
