daggerheart-foundry-mcp-adapter
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@daggerheart-foundry-mcp-adapter Make a duality roll for Valen and update their hope and fear in the scene."
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.
Ninjo's Foundry MCP
Ninjo's Foundry MCP lets an AI assistant that speaks the Model Context Protocol (MCP), such as Claude Desktop, Claude Code or Cursor, work with your Foundry VTT world. Ask it to read and write journals, build scenes, search compendiums, manage actors, tokens, combat, chat, roll tables, playlists and more. It works only as far as the Gamemaster allows.
How it works
It has two parts that you install separately:
The Foundry module
ninjos-foundry-mcpruns in the Gamemaster's browser. It connects to the server on the same computer and carries out every request inside the world, after checking the permissions described below. Only a Gamemaster connects.The PC server runs on the Gamemaster's computer. Your MCP client starts it; all clients share one background process, which talks to the module over a local WebSocket on port 31415. Nothing is reachable from other computers.
The module and the server are updated independently. A server and a module one version apart still work together.
Related MCP server: Foundry VTT MCP Server
Installation
Module: in Foundry under "Add-on Modules", install "Ninjo's Foundry MCP" and enable it in your world.
Server: download
ninjos-foundry-mcp-server-<version>-win32-x64.zipfrom the releases page, unpack it and double clicksetup.cmd. No Node.js and no administrator rights are needed.Restart Claude Desktop, open your world as Gamemaster and ask: "Which world is open in Foundry?"
Updating from 14.2609.3 or older: the module update alone is not enough, set up the server on your PC anew with the new server package as in step 2; a notice in Foundry explains this after the update.
Setup takes over an installation from the previous installer in place: same folder, same entry, your settings stay. Details, Claude Code, other clients, updating, uninstalling and troubleshooting: docs/INSTALLATION.en.md (German: docs/INSTALLATION.md).
Permissions
Every change goes through one check in the module, whichever tool asks for it:
"Allow Write Operations" is the master switch. Off means the assistant can only read.
A permission level per document kind (scenes, playlists, journals, roll tables, actors, folders, compendiums): read only, create and change, or create, change and delete. The default is create and change.
Deleting is off by default for every kind, because it is the one change that cannot be undone. Turn it on per kind if you want it. Items, macros, card stacks, chat messages and combat encounters have no level yet: they can be created and changed while the switch is on, and deleting them is refused.
Running macros is off by default. Destructive tools can additionally require a one-time confirmation with a dry run first ("Confirm destructive tools").
Every change is logged.
list-changesshows the log,undo-changereverts an entry or a whole call where that is possible.
Supported systems
Foundry VTT 13 and 14 (verified on 14).
Game systems: the core tools (journals, scenes, compendiums, folders, playlists, roll tables, canvas, combat, chat, files) work in every system. System knowledge comes from adapters for D&D 5e, Pathfinder Second Edition, Das Schwarze Auge 5, Warhammer Fantasy Roleplay 4e, the Cosmere RPG, Traveller and basic Daggerheart support (scope and local setup). Without an adapter a tool that needs one says so.
Server: Windows 10 and 11. A macOS bundle is not published yet.
MCP clients: Claude Desktop (including the Store edition), Claude Code, Cursor and any client that starts MCP servers through
commandandargs.Browser: Foundry must run in a browser on the same computer as the server.
Tools of other modules
Other Foundry modules can offer their own tools through this module. The interface is described in docs/EXTENSION-TOOLS.md.
Development
Node 24 or later.
npm ci
npm run check # typecheck, language files, tests
npm run build # server to build/, module scripts and languages to module/
npm run build:test-module # module copy for a manual test deployment, see below
node installer/build.mjs --no-zipnpm run build:test-module writes dist/test-module/ninjos-foundry-mcp/ without the
manifest and download fields and with a -test.<time> version suffix, so Foundry
never replaces a test deployment with the release from the package listing.
Tests never use the ports 31414 to 31416, so they do not disturb a running installation.
License
Not open source. Free to use, also for paid games, but not to redistribute, copy into other projects or sell without permission. See LICENSE (English and German, the German version applies). Third-party material and its licences are listed there. The Ninjo logo is excluded from any licence.
Versions before 14.2609.4 were released under the MIT License and stay under it. Version 14.2609.4 is a rewrite and contains none of the code of the project those versions were forked from.
Available Tools
152 toolsactor-refresh-from-sourceRefresh actor items from their sourceADestructiveIdempotent
Items on an actor are copies. When their compendium was translated or corrected later, the copies keep the old text. This pulls name, image and description again from each item's source, and never touches mechanics: levels, uses, prepared spells, quantity, equipment and attunement stay. Items without a resolvable source are listed and left alone. Always run dryRun first.
Inputs: actorIdentifier (required), dryRun, fields, namePacks, +1 more.
actor-set-tokenSet the token image of an actorADestructiveIdempotent
Set an actor's prototype token image, and optionally its portrait, its token name and the dynamic token ring. With ring true the token image also becomes the subject inside the ring, and without ringColor the ring is coloured by disposition: hostile red, neutral blue, friendly green. The actor is found by id or exact name.
Inputs: tokenImg (required), actorIdentifier (required), ring, ringColor, +3 more.
add-combatantsAdd combatantsAIdempotent
Add tokens to a combat encounter as combatants. Tokens come from the encounter's scene (for an encounter without scene: sceneIdentifier or the active scene). One unknown id stops everything; tokens already in the encounter are named and not added twice.
Inputs: tokenIds (required), dryRun, combatId, sceneIdentifier.
advance-world-timeAdvance the world timeA
Move the world time forward (or back with a negative number) by a number of seconds, through Foundry, so effects, calendars and modules react as at the table. 3600 is an hour and 86400 a day in the default calendar. The new time is read back. Needs the write switch.
Inputs: seconds (required), dryRun.
assign-actor-ownershipAssign actor ownershipAIdempotent
Give players a permission level on actors, e.g. make John the owner of Aragorn, or give the party observer access to all friendly NPCs of the active scene. Actors and players are matched exactly (id or name, case does not matter), never by part of a name; Gamemasters are never changed. More than one actor or player needs confirmBulkOperation. Each pair is read back and reported, unchanged pairs included.
Inputs: actorIdentifier (required), permissionLevel (required), playerIdentifier (required), confirmBulkOperation.
browse-filesBrowse filesARead-onlyIdempotent
List folders and files in one folder of Foundry's data storage (source data, default) or of Foundry's own public files (source public). Paths are relative, such as "worlds//maps". Up to 500 entries each.
Inputs: path, source, extensions.
change-combat-turnChange combat turnA
Move a running combat encounter: next-turn, previous-turn, next-round, previous-round, or set-turn to a combatant. Moves use Foundry's own rules (for example skipping defeated combatants when the tracker is set so). The answer gives round and turn before and after.
Inputs: action (required), tokenId, combatId, combatantId.
check-wall-collisionDo walls block a line?ARead-onlyIdempotent
Test whether walls block the straight line between two tokens or points, for movement, sight, light or sound, and list the walls on it. Doors that are open do not block. Uses Foundry's own test when the canvas shows the scene, otherwise the stored walls.
Inputs: to (required), from (required), type, sceneIdentifier.
control-playlistControl playlist playbackA
Play or stop a playlist or one of its tracks, or switch its mode, through Foundry's own playback, so every connected browser follows. Playlist and track are found by id or exact name (case ignored when unique), never by a part of the name. The state is read back: a playlist without tracks or in mode "disabled" is an error, not a silent success. Browsers may only play sound after someone clicked on the page once. Needs the playlist permission "create and change".
Inputs: command (required), playlist (required), sound.
copy-fileCopy a fileADestructiveIdempotent
Copy a file (at most 50 MiB) inside Foundry's data storage into an existing folder. The original stays: Foundry cannot delete files. To move files: find-file-references on the old path, copy-file, then world-rewrite-paths (dryRun first), then find-missing-files. Needs the write switch.
Inputs: to (required), from (required), name, dryRun, +1 more.
create-actor-from-compendiumCreate actors from a compendiumA
Copy one actor entry of a compendium into the world, once per name, into the folder "Foundry MCP Creatures", and optionally place the copies as tokens in the active scene. Find packId and itemId with search-compendium first. At most 10 copies (and not more than the setting "maxActorsPerRequest"). The copy keeps a link to its entry, never its id; a remote token image is dropped so Foundry uses its default. Everything that could refuse, including the scene permission for addToScene, is checked before the first actor is created. The answer lists every actor with its real name, the placed tokens and every problem.
Inputs: names (required), itemId (required), packId (required), quantity, +2 more.
create-campaign-dashboardCreate a campaign dashboardA
Create a journal that gives an overview of a campaign in several parts: progress, current part, location and quest giver, and for each part its levels, description and a status toggle. Clicking a toggle in Foundry cycles not started, in progress, completed, skipped and saves it on the journal; figures, current part and lock markers follow the saved status whenever the page is shown. A part is locked until the one before it is completed or skipped. The journal is visible to Gamemasters only, named after the campaign and placed in a journal folder with the campaign title (created when missing). Texts are written in the language of the Gamemaster's client.
Inputs: template (required), campaignTitle (required), campaignDescription (required), customParts, +2 more.
create-canvas-elementsCreate walls, lights and other canvas elementsA
Create up to 200 elements of one type on a scene in one call, as Foundry data. Walls: c [x0, y0, x1, y1], door none, door or secret, doorState closed, open or locked, move none or normal, sight, light and sound none, limited, normal, proximity or distance, dir both, left or right. Lights: x, y, config { dim, bright, color, angle }. Sounds: x, y, radius, path. Tiles: x, y, width, height, texture { src }. Drawings: x, y, shape { type, width, height, points }. Regions: name, shapes, behaviors. One bad entry creates nothing. Needs the level "change" for scenes.
Inputs: elements (required), elementType (required), dryRun, sceneIdentifier.
create-card-deckCreate a card deckA
Create a card deck from a list of cards (or an empty hand or pile to deal into). Each card has a name and optionally text, image, suit and value. Read back with the cards in the given order.
Inputs: name (required), img, type, cards, +3 more.
create-combatCreate combat encounterA
Create a combat encounter on a scene (the active scene by default) and optionally add tokens as combatants. It does not start the encounter; start-combat does. Tokens are named by id only.
Inputs: dryRun, activate, tokenIds, unlinked, +1 more.
create-compendiumCreate compendiumA
Create a new world compendium, for example to archive a finished chapter of a campaign. Choose the document type it will hold. Needs the compendium permission on "create and change".
Inputs: type (required), label (required).
create-directoryCreate a folderAIdempotent
Create a folder in Foundry's data storage, with any missing folders above it. Never inside modules, systems or another world. An existing folder is left as it is. Needs the write switch.
Inputs: path (required), dryRun.
create-documentCreate a document of any typeA
Generic fallback: create one document of any type in the world, or inside another document with parentUuid (a page in a journal, an item on an actor, a wall on a scene). data holds the fields as nested objects, as describe-document-type shows them. The permission settings apply as for the specialised tools; ids, ownership, _stats and the flags of this module cannot be given. The answer is read back from Foundry. Use dryRun first. Prefer journal-create, journal-add-page, create-scene, manage-actors, manage-world-items, create-macro and create-roll-table where they fit. Chat messages are sent only with send-chat-message; settings, users and compendiums are not written here.
Inputs: data (required), documentType (required), dryRun, parentUuid.
create-dsa5-character-from-archetypeCreate a DSA5 character from an archetypeA
[DSA5 only] Create one hero as a copy of an archetype from list-dsa5-archetypes, with a new name and optional details (age, biography, gender, eye and hair color, height, weight, species, culture, profession) written onto the hero and read back. The hero goes into the folder "Foundry MCP Actors", without a token in a scene, linked to its archetype. A name another actor has already (ignoring case) is refused. addToWorld false only prepares the hero and shows it, without writing anything.
Inputs: archetypeId (required), characterName (required), archetypePackId (required), addToWorld, +1 more.
create-macroCreate a macroA
Create a macro. A chat macro holds chat text or a chat command such as /roll 1d20. A script macro holds JavaScript that can do anything a Gamemaster can once someone runs it. Creating runs nothing.
Inputs: name (required), type (required), command (required), img, +1 more.
create-quest-journalCreate a quest journalA
Create a quest journal visible to Gamemasters only. Its first page holds the title and description, a background from location, quest giver and key figure, an overview with the given details, rewards and "Status: Active", an adventure hook as read-aloud text, a secret note for the Gamemaster, objectives from the quest type and the given facts, and a section for progress notes. All given values are escaped, so they appear as text. Write richer content yourself into additionalPages, which are stored as sent. Without folderName the journal is created outside any folder. The answer lists the pages with their ids and lengths, not the HTML.
Inputs: questTitle (required), questDescription (required), npcName, rewards, +6 more.
create-roll-tableCreate a roll tableA
Create a roll table from a list of text results. Ranges are assigned consecutively when omitted (first entry 1, second 2, and so on) and the dice formula is derived from the highest range, so a six-entry table becomes 1d6 by itself. Overlapping ranges are refused; gaps, and numbers the formula can roll without an entry, are reported as warnings.
Inputs: name (required), results (required), formula, folderPath, +1 more.
create-sceneCreate sceneA
Create a scene from an image or video already in the Foundry data directory, such as a battlemap or a location picture. Without width and height the file is measured so the grid fits. templateName copies the settings of an existing scene (grid, lighting, level settings) but nothing that lies on its map and never its id. folderPath takes nested paths like "Locations/Harbour" and creates missing folders. journalIdentifier links a journal as the scene journal.
Inputs: name (required), background (required), width, height, +9 more.
create-scene-notePlace a journal noteA
Place a note on a scene at pixel coordinates that opens a journal, or one page of it, when clicked. Useful to make the places on a town map clickable.
Inputs: x (required), y (required), journalName (required), sceneIdentifier (required), +4 more.
deal-cardsDeal cardsA
Deal the same number of cards from one stack to each of several hands or piles. Refused before anything moves when too few cards are left. Needs the write switch.
Inputs: to (required), from (required), how, number, +1 more.
delete-canvas-elementsDelete walls, lights and other canvas elementsADestructiveIdempotent
Delete up to 200 elements of one type from a scene by id. Every id is checked first. Deleting needs the level "create, change and delete" for scenes, which is off by default; dryRun shows what would go and whether it is allowed.
Inputs: ids (required), elementType (required), dryRun, sceneIdentifier.
delete-card-stackDelete a card stackADestructiveIdempotent
Delete a card stack by id. Card stacks have no level of their own in the permission settings yet, so deleting is refused until they get one.
Inputs: stackId (required).
delete-chat-messageDelete a chat messageADestructiveIdempotent
Delete a chat message written by the Gamemaster the bridge runs as, by id. Refused until the permission settings have a level for chat messages that allows deleting.
Inputs: messageId (required).
delete-compendiumDelete compendiumADestructiveIdempotent
Remove a world compendium and everything in it. This cannot be undone, so it is off by default: the compendium permission has to stand on "create, change and delete". The exact label must be passed as confirmLabel. Compendiums of a module or of the game system cannot be removed this way.
Inputs: packId (required), confirmLabel (required).
delete-compendium-entriesDelete compendium entriesADestructiveIdempotent
Remove named entries from a compendium, by id or by exact name. Only what is explicitly named is removed; there is deliberately no "empty this pack". Always run with dryRun first: it reports exactly what would go, what was not found and which names are ambiguous, without touching anything. Names are matched in their exact spelling, never as a part, and an ambiguous name is reported rather than guessed. If the selection covers every entry, confirmLabel is required as well. Needs the compendium permission on "create, change and delete".
Inputs: packId (required), ids, names, dryRun, +2 more.
delete-documentDelete a document of any typeADestructiveIdempotent
Generic fallback: delete one document of any type, by uuid or by documentType and id. Needs the level "create, change and delete" of its kind, for an embedded document that of the document it belongs to; kinds without a level cannot be deleted. Refused for a folder with contents, a playlist or track a scene is linked to, the active scene and chat messages of others. dryRun shows what would go, embedded documents included. Prefer journal-delete, journal-delete-page, delete-scene, manage-actors, delete-playlist, delete-roll-table and delete-tokens where they fit. Compendium entries are deleted with delete-compendium-entries.
Inputs: id, uuid, dryRun, parentUuid, +1 more.
delete-playlistDelete a playlistADestructiveIdempotent
Delete a playlist by its id. Refuses while the playlist is still linked to a scene, and names those scenes. Requires the playlist permission to be set to full.
Inputs: playlistId (required).
delete-roll-tableDelete a roll tableADestructiveIdempotent
Delete a roll table by its id. Requires the roll table permission to be set to full.
Inputs: tableId (required).
delete-sceneDelete sceneADestructiveIdempotent
Delete a scene for good, by its id only, so a scene with a similar name is never hit. The active scene is never deleted; activate another one first. Needs the scene permission on "create, change and delete".
Inputs: sceneId (required).
delete-tokensDelete tokensADestructiveIdempotent
Remove tokens from the active scene (or the scene in sceneIdentifier), by their ids only. The actors stay in the actor directory; an unlinked token loses its own values with it. When one id is not on the scene, nothing is deleted and the answer says where that id lies. The answer lists every deleted and every failed token.
Inputs: tokenIds (required), sceneIdentifier.
describe-document-typeDescribe a document typeARead-onlyIdempotent
List the document types of this Foundry, or describe one: its fields from Foundry's data model, its subtypes, the system fields of a subtype in the active game system, what it holds and belongs to, the permission level writing it needs, the fields generic access never changes, and the specialised tools for it. Call it before creating or changing a type through generic access for the first time.
Inputs: depth, subtype, documentType.
dnd5e-add-featureAdd a D&D 5e featureA
[D&D 5e only] Add one thing to an existing dnd5e NPC or character; featureType chooses what, and each kind reads only its own parameters (the answer names the ignored ones).
passive: a trait without a roll. Needs featureName.
save: a feature forcing a saving throw with fixed DC, damage, optional template. Needs featureName, saveAbility, saveDC, damageParts; areaSize with areaType.
attack: a weapon attack. Needs featureName, attackType, damageParts; rangeFt when ranged. The first damage part is the weapon damage.
attack-with-save: an attack whose hit also forces a save with its own damage. Needs in addition saveAbility, saveDC, saveDamageParts.
aura: area damage without attack or save; no lasting aura or effect is created. Needs featureName, damageParts, areaType, areaSize.
spellcasting: casting ability and caster level of an NPC without class items, per class, level and rules version (2024 paladins and rangers have slots at level 1). dnd5e derives the slots; actors with class items are refused. Needs spellcastingClass, spellcastingLevel.
spells: copy spells by English name from compendiums. Needs spellNames. An item name the actor already has (ignoring case) is refused. The actor is found by id, exact name or token id, never by part of a name. Everything written is read back. Run spellcasting before spells.
Inputs: featureType (required), actorIdentifier (required), saveDC, rangeFt, +29 more.
dnd5e-add-features-from-compendiumAdd D&D 5e features from compendiumsA
[D&D 5e only] Copy class and monster features by English name from item compendiums onto an actor, such as "Pack Tactics", "Multiattack" or "Action Surge". Names match whole and ignoring case; the first compendium in compendiumPacks with the name wins, and two entries of that name in one compendium are reported instead of guessed. Without compendiumPacks the standard compendiums of the world's rules version are searched (2024 class features are part of the class items and cannot be fetched one by one). Items the actor already has by name are skipped. Copies keep a link to their entry, never its id. The answer lists added, skipped, not found and failed names; for spells use dnd5e-add-feature with featureType "spells", for homebrew features featureType "passive" and the others.
Inputs: featureNames (required), actorIdentifier (required), compendiumPacks.
dnd5e-create-npcCreate a D&D 5e NPCA
[D&D 5e only] Create one NPC with a complete stat block and no items: type, size, alignment, challenge rating, ability scores, saving throw and skill proficiencies, hit points, armor class, speeds, senses, damage and condition traits, languages, biography and source. It goes into the folder "Foundry MCP Creatures". A name any actor already has (ignoring case) and a challenge rating the rules do not have are refused. Proficiency bonus and experience points are left to dnd5e, which derives them. Every value is read back; the answer lists warnings (e.g. a language that is not a dnd5e key) and anything stored differently. Add attacks, features and spells afterwards with dnd5e-add-feature.
Inputs: cr (required), name (required), size (required), acMode (required), +30 more.
draw-cardsDraw cardsB
Draw cards from one stack (usually a deck) into another (usually a hand or pile). Refused before anything moves when too few cards are left. Every card is looked up afterwards. Needs the write switch.
Inputs: to (required), from (required), how, number, +1 more.
draw-roll-tableDraw from a roll tableA
Roll on a roll table and return the entries. mode "draw" follows the table: a table without replacement marks drawn entries so they do not come again. mode "roll" never marks anything. Nothing goes to the chat unless chat is set.
Inputs: tableId (required), chat, mode, count.
end-combatEnd combatADestructiveIdempotent
End a combat encounter: it stops (round 0, not active) and keeps its combatants and initiatives. deleteEncounter deletes it instead, as Foundry's own End Combat does; deleting encounters is refused until they have a permission level.
Inputs: dryRun, combatId, deleteEncounter.
execute-macroRun a macroADestructive
Run a macro in the Gamemaster's browser and report its result or error. Off by default: the world setting "macroExecution" must be "chat" for chat macros or "all" for script macros. A SCRIPT MACRO CAN DO ANYTHING a Gamemaster can, including deleting documents, and cannot be undone; read its command with list-macros first. A chat macro only posts to the chat.
Inputs: macroId (required), args, alias, sceneId, +2 more.
export-to-compendiumExport to compendiumADestructiveIdempotent
Copy documents from the world into a compendium, to archive finished material. Select by name or id, or by the world folder they sit in; without either, everything of that type is copied. Ids are kept, so a document already in the compendium is overwritten instead of duplicated. A locked compendium is refused unless unlockIfNeeded is set; then the lock is lifted for this operation only and set again afterwards. The answer lists new, overwritten, skipped and, marked CAUTION, lost entries.
Inputs: packId (required), documentType (required), names, folderName, +1 more.
find-file-referencesFind documents that use a pathARead-onlyIdempotent
Find every field of every world document that points to a file or folder path, with the same path rule world-rewrite-paths uses: a folder matches the files under it, never a longer name. Use it before moving or replacing files. Compendiums are not scanned.
Inputs: path (required), maxResults, collections.
find-missing-filesFind missing filesARead-onlyIdempotent
Find files that world documents point to but that do not exist: images, sounds, videos, text and fonts in fields and in markup, looked up in the data storage and in Foundry's own files. Wildcard paths are counted but not checked. Compendiums are not scanned.
Inputs: under, maxResults, collections, maxDirectories.
find-pathFind a path around wallsARead-onlyIdempotent
Find a way from a token or point to another around walls that block movement (or sight, light, sound), on square and gridless scenes, and its length. Moves nothing; move-token moves a token. Works without a drawn canvas.
Inputs: to (required), from (required), type, maxCells, +1 more.
find-tokens-in-rangeTokens in rangeARead-onlyIdempotent
List the tokens within a distance (scene units) of a token or point, nearest first, optionally only those not hidden behind walls for sight. Works without a drawn canvas.
Inputs: from (required), distance (required), includeHidden, sceneIdentifier, +1 more.
folder-deleteDelete a folderADestructiveIdempotent
Delete a sidebar folder, found by its id or exact name. By default its documents and subfolders move up one level. With deleteContents true, all documents and subfolders inside are deleted as well. Needs the folder permission level "create, change and delete", and for deleteContents the same level for the documents inside.
Inputs: folderName (required), type, deleteContents.
folder-renameRename a folderAIdempotent
Rename a sidebar folder, found by its id or exact name, optionally only among folders of one document type. When several folders have that name, the error lists them so the id can be passed instead. Contents stay.
Inputs: newName (required), folderName (required), type.
get-available-conditionsAvailable conditionsARead-onlyIdempotent
List the conditions the game system of the world offers in Foundry, with id, name, icon and description. Use it to find the id for toggle-token-condition.
Inputs: no named parameters.
get-canvas-viewWhat the canvas showsARead-onlyIdempotent
Whether the Gamemaster's browser has a drawn canvas, which scene it shows and which is active, the view position and zoom, and the Gamemaster's targets. Call it before pan-camera, ping-canvas or set-targets, which need the canvas.
Inputs: no named parameters.
get-card-stackRead a card stackARead-onlyIdempotent
Read one card stack with its cards in order: name, suit, value, drawn, text, image and origin.
Inputs: stackId (required), includeDrawn.
get-characterGet characterARead-onlyIdempotent
Overview of one actor with few tokens: head values and the value block as the adapter of the game system reads them, every item with id, name and type (plus the fields the system marks as relevant, no descriptions), effects, actions and spellcasting where the system has them. Without an adapter for the game system only name, type and image are known, and notes says so. The actor is found by id, exact name or token id; similar names are suggested, never guessed. Fetch the full data of one item or effect with get-character-entity.
Inputs: identifier (required).
get-character-entityGet character entityARead-onlyIdempotent
Full data of one item, action or effect of an actor: description, all system data (credentials removed, game data such as save or activity data kept) and its effects. Looks among items first (id or exact name), then actions, then effects; two entries of the same name are reported with their ids instead of picking one.
Inputs: entityIdentifier (required), characterIdentifier (required).
get-combatGet combat encounterARead-onlyIdempotent
Read one combat encounter: the turn order with initiative, hidden and defeated flags, and the current turn with its actor (values from the game system adapter where there is one), token, conditions and who comes next.
Inputs: combatId.
get-compendium-entry-fullGet compendium entry in fullARead-onlyIdempotent
One compendium entry of any document type with everything needed before copying it into the world: name, type, compendium label, description, system data, every contained item with its system data, the effects, a short summary and the whole document. Credentials are removed. A missing compendium or entry is reported as such.
Inputs: packId (required), entryId (required).
get-compendium-itemGet compendium itemARead-onlyIdempotent
Retrieve one compendium entry in full: name, type, description, image, system data, contained items and effects and the whole document. compact returns key values, properties and at most five contained items instead, which is enough to decide between candidates.
Inputs: itemId (required), packId (required), compact.
get-current-sceneCurrent sceneARead-onlyIdempotent
Describe the scene that is active for everyone: size, background, navigation, how many walls, lights, sounds and notes it holds, its notes, and with includeTokens its tokens. Hidden tokens are left out of the list and the summary unless includeHidden is set.
Inputs: includeHidden, includeTokens.
get-documentRead one document of any typeARead-onlyIdempotent
Generic fallback: read one document of any type by uuid, or by documentType and id (with parentUuid for an embedded document, pack for a compendium), whole or only the given fields. A large answer comes in parts: call again with chunkStart and the fingerprint of the first part and join the parts. embedded "summary" shortens embedded collections to ids and names. Prefer get-character, get-current-scene, get-roll-table, get-compendium-item and get-token-details where they fit.
Inputs: id, pack, uuid, fields, +6 more.
get-permissionsPermissionsARead-onlyIdempotent
Show what the AI is currently allowed to do in this world: the switch "Allow Write Operations", the level per document kind (scenes, playlists, journals, roll tables, actors, folders, compendiums: read only, create and change, or additionally delete), the release list of compendiums and the modules released to offer tools of their own. Deleting is off by default everywhere. Call this when an action was refused, to see which setting has to change.
Inputs: no named parameters.
get-roll-tableRead a roll tableARead-onlyIdempotent
Read one roll table with its settings and every entry: id, range, weight, text and whether it is drawn. The entry ids are what update-roll-table needs.
Inputs: tableId (required).
get-scene-imageScene imageARead-onlyIdempotent
Take a picture of a scene so you can look at the map. Returns one image and, as JSON, every token with its number on the picture, name, grid cell, canvas position, size, disposition and hidden flag, plus the grid (type, cell size, distance) and how canvas pixels map to picture pixels. Grid labels on the picture count cells from 0 at the top left of the scene, the same numbers as the token list. When the GM views the scene, the rendered canvas is captured (background, tiles, drawings, token art; no lighting, fog or vision). Otherwise, or with mode "composed", the picture is the background with grid and numbered token markers. Read only.
Inputs: grid, mode, format, region, +5 more.
get-token-detailsToken detailsARead-onlyIdempotent
Read one token: position, size, appearance (rotation, scale, alpha, hidden, image), behaviour (disposition, elevation, rotation lock) and its actor with whether it is linked. Hidden tokens are read too. No actor values such as hit points; get-character reads those.
Inputs: tokenId (required), sceneIdentifier.
get-world-infoWorld informationARead-onlyIdempotent
Read the basics of the Foundry world that is open right now: its id and title, the game system and its version, the Foundry version, how many users exist, and who is logged in. Use it first to learn which world and system you are working with.
Inputs: no named parameters.
get-world-timeRead the world timeARead-onlyIdempotent
Read Foundry's world time in seconds, formatted by the world's calendar when one is configured, and whether the game is paused.
Inputs: no named parameters.
import-from-compendiumImport from compendiumA
Copy a document out of a compendium into the world: playlists, scenes, journals, actors, roll tables, items, macros, cards. Always assigns a FRESH id, so it can never overwrite an existing world document. That is the difference to dragging an entry out by hand, which keeps the id and silently replaces whatever carries it. Names are matched as a whole; an ambiguous name is refused with the ids.
Inputs: packId (required), entryId, newName, entryName, +1 more.
journal-add-pageAdd a pageA
Add a new text page at the end of a journal, with the HTML stored as sent.
Inputs: html (required), name (required), journalId (required).
journal-append-pageAppend to a pageA
Append HTML to the end of a text page. Meant for content too large for one message: create the page with the first part, then append the rest in pieces of about 40000 characters. The pieces are joined as sent, so cut them between tags. Returns the new length.
Inputs: html (required), pageId (required), journalId (required).
journal-createCreate a journalA
Create a journal with exactly the given pages, in order, each stored as HTML exactly as sent (headings, images and @UUID links included). No template page is added. Only Gamemasters can see it. With folderName the journal goes into that journal folder (by id or exact name), which is created when it does not exist; without folderName it is created outside any folder. Returns the new journal id.
Inputs: name (required), pages (required), folderName.
journal-deleteDelete a journalADestructiveIdempotent
Delete a whole journal with all its pages for good. Needs the journal permission level "create, change and delete", which is off by default.
Inputs: journalId (required).
journal-delete-pageDelete a pageADestructiveIdempotent
Delete one page of a journal for good. Needs the journal permission level "create, change and delete", which is off by default.
Inputs: pageId (required), journalId (required).
journal-link-tagsLink 5etools tagsADestructiveIdempotent
Turn leftover 5etools tags, @creature[Name|Source] and @item[Name|Source] with an optional third part as label, into Foundry links to compendium entries. Creatures are looked up in actorPacks, items in itemPacks, in the given order, by name ignoring case; for creatures the id of the official 2024 books is tried as well, so an English tag also finds a translated compendium. Every tag that could not be resolved is listed. Use dryRun first.
Inputs: journalId (required), dryRun, pageId, itemPacks, +1 more.
journal-page-from-fileFill a page from a fileADestructive
Write an HTML file that is already in Foundry's data directory into a page. The browser fetches the file from the Foundry server itself and nothing of it crosses the bridge, so any size works. With pageId that text page is overwritten (an unknown pageId is an error); without it a new text page is added at the end.
Inputs: path (required), journalId (required), pageId, pageName.
journal-renameRename a journalBIdempotent
Give a journal a new name.
Inputs: newName (required), journalId (required).
journal-rewrite-imagesPoint images to local filesADestructiveIdempotent
Replace external image addresses in text pages with local paths, for imported adventures that load their images from a CDN. Every img whose src starts with urlPattern (ignoring case) gets localPrefix followed by the file name of the old address. Runs inside Foundry. Use dryRun first.
Inputs: journalId (required), urlPattern (required), localPrefix (required), dryRun, +1 more.
journal-set-pageReplace a pageADestructiveIdempotent
Replace the whole HTML content of a text page with the given HTML, stored as sent. Nothing is appended or wrapped. For content larger than one message, write the first chunk here and add the rest with journal-append-page, or use journal-page-from-file.
Inputs: html (required), pageId (required), journalId (required).
journal-split-pageSplit a page at headingsADestructive
Split a large text page into one page per section, cut at headings, inside Foundry so the content never crosses the bridge. The markup of each section is kept as it was. Content before the first heading becomes a page of its own. The new pages appear right behind the source page, which is kept unless deleteOriginal is true.
Inputs: pageId (required), journalId (required), level, namePrefix, +1 more.
link-quest-to-npcLink a figure to a questAIdempotent
Add a figure with its role to the list of related figures on the first text page of a quest journal. When an actor with this id or exact name exists in the world, the entry is a link to it; otherwise the name is written as text and the answer says so. Several actors with that name are an error listing their ids. The list is created once (in the overview of a page from create-quest-journal, else at the end of the page) and extended afterwards; the same figure in the same role is not added twice. The page is changed as a whole inside Foundry, so nothing of a long page is lost.
Inputs: npcName (required), journalId (required), relationship (required).
list-actor-ownershipList actor ownershipARead-onlyIdempotent
Show which level every player effectively has on actors, and whether it is set for that player or comes from the default level of the actor. One actor or all, one player or all; Gamemasters are left out because they own everything.
Inputs: actorIdentifier, playerIdentifier.
list-canvas-elementsList walls, lights and other canvas elementsARead-onlyIdempotent
List the walls (with doors), lights, sounds, regions (with behaviors), tiles and drawings of a scene, with ids and their main fields. Filter by type, by an area in pixels or to doors only. Works without a drawn canvas.
Inputs: raw, limit, bounds, offset, +3 more.
list-card-stacksList card stacksARead-onlyIdempotent
List the card decks, hands and piles of the world with their card counts.
Inputs: type.
list-changesList recent changesARead-onlyIdempotent
List the changes the AI made to the world, newest first, from the change log of this session: when, by which Gamemaster, which tool, which documents, and whether each can be undone (and why not). Every entry has an id and the id of its tool call for undo-change. The log keeps the latest 200 changes and starts empty when the Gamemaster reloads the world.
Inputs: tool, limit, callId, document.
list-charactersList charactersARead-onlyIdempotent
List the actors of the world with id, name, type, folder and whether they have an image, optionally of one type. When no actor has the given type, the answer names the types that exist.
Inputs: type.
list-chat-messagesList chat messagesARead-onlyIdempotent
Read the chat log as the Gamemaster sees it, newest first, whispers included, each with who it is whispered to. Filter by speaker, author, type, time or what one user can see, and page back with beforeId. Content is shown as plain text.
Inputs: type, limit, since, author, +4 more.
list-combatsList combat encountersARead-onlyIdempotent
List every combat encounter of the world with its scene, whether it is active and started, round, turn, number of combatants and who acts now.
Inputs: no named parameters.
list-compendium-entriesList compendium entriesARead-onlyIdempotent
List what actually sits inside a compendium: ids, names, types and folders. list-compendiums only gives counts, so this is the way to check whether an archive holds what it should, to find duplicates, or to get the ids needed for later work. Reads the index only, never the full documents, and returns at most 1000 entries per call; when more follow, the answer says so with the next offset. Read only: it changes nothing and works at any permission level.
Inputs: packId (required), limit, offset, folderName, +1 more.
list-compendium-packsList compendium packsARead-onlyIdempotent
List all compendium packs with id, label, document type, game system and whether they are private, optionally filtered by document type. availableTypes names every type that occurs, also when a filter is set.
Inputs: type.
list-compendiumsList compendiumsARead-onlyIdempotent
List every compendium with its type, entry count, lock state and whether the AI can write to it right now. "Editable" takes all layers into account: the write switch, the permission level for compendiums, the release list and the lock. An unlocked compendium can be written to no matter who ships it, unless the release list is filled. Call this before exporting to find the right pack id.
Inputs: no named parameters.
list-creatures-by-criteriaList creatures by criteriaARead-onlyIdempotent
Creature discovery for encounter building: a long list of creatures matching criteria, with little data per creature, so you can choose by name and fetch details with get-compendium-item only for the final selection. The filters are understood by the adapter of the active game system (D&D 5e: challenge rating, creature type, size, alignment, spells, legendary actions; Pathfinder 2e: level, traits, rarity; DSA5: experience level, species, culture, profession; WFRP4e: species, traits, prayers; Traveller: hits, psionics; Cosmere RPG: tier, role, defenses; Daggerheart: tier, adversaryType, difficulty, hitPoints, stress) and checked against the creature index. Filters the active system does not know are reported as ignored. Without an adapter for the system, filtering is refused and a call without filters lists every actor by name.
Inputs: hits, role, size, tier, +24 more.
list-documentsList documents of any typeARead-onlyIdempotent
Generic fallback: list documents of any type in the world, inside one document (parentUuid) or in a compendium (pack, read only), with conditions, sorting, paging and field selection. Prefer the specialised tools where one fits: list-journals, list-scenes, list-characters, list-compendium-entries, list-chat-messages, list-macros, list-playlists, list-roll-tables. Use this for types they do not cover (Combat, Cards, Wall, Region, Drawing), for game systems without an adapter, or to get exactly the fields needed. Without fields each row shows id, uuid, name, type and folder. describe-document-type shows the field paths.
Inputs: documentType (required), pack, limit, where, +6 more.
list-dsa5-archetypesList DSA5 archetypesARead-onlyIdempotent
[DSA5 only] Find archetypes (ready made heroes of type character) in the actor compendiums of the dsa5 system, e.g. from the DSA5 core rules module, to create a hero with create-dsa5-character-from-archetype. Each archetype comes with id, name, compendium, species, profession and image. filterBySpecies matches the whole species ignoring case, filterByProfession a part of the profession ignoring case. A compendium that cannot be read is named with its cause.
Inputs: packId, filterBySpecies, filterByProfession.
list-journalsList or read journalsARead-onlyIdempotent
Without journalId: every journal with its pages (id, name, type). With journalId: the content of its first text page and the list of all its pages. With journalId and pageId: the content of that page; for image, video or PDF pages the content is the source address. Content comes in chunks of maxChars characters: when hasMore is true, call again with offset set to nextOffset, and never write a partial chunk back as the whole page.
Inputs: offset, pageId, maxChars, journalId, +2 more.
list-macrosList macrosBRead-onlyIdempotent
List the macros of the world with type (chat or script), folder, author and whether the AI may run them now. includeCommand shows the command text.
Inputs: type, nameContains, includeCommand.
list-playlistsList playlistsARead-onlyIdempotent
List the playlists in the world with their sounds. Use this to find the exact playlist and sound name before linking one to a scene, or to check whether a playlist referenced by a journal actually exists in the world.
Inputs: includeSounds.
list-roll-tablesList roll tablesARead-onlyIdempotent
List the roll tables in the world with their formula and number of results.
Inputs: no named parameters.
list-scene-foldersList scene foldersARead-onlyIdempotent
List every scene folder with its full path, its id and how many scenes lie directly in it. Call it before create-scene or update-scene to pick a valid folderPath.
Inputs: no named parameters.
list-scenesList scenesARead-onlyIdempotent
List the scenes of the world with id, name, whether active, size, grid size, background and how many walls, tokens, lights and sounds each holds. filter narrows by a part of the name, in any case.
Inputs: filter, include_active_only.
list-settingsList settingsARead-onlyIdempotent
Read registered world and client settings of the core ("core") or of chosen modules and systems, with name, scope, type and value. Values whose key looks like a secret are hidden, and the settings of this MCP module are not listed (get-permissions shows them). Client settings are those of the Gamemaster browser.
Inputs: limit, scope, namespaces, keyContains, +1 more.
list-usersList usersARead-onlyIdempotent
List the users of the world with role, whether they are logged in, their assigned character and the scene they are viewing. No passwords or access data.
Inputs: onlyActive.
manage-actorsManage actorsADestructive
Create, change, delete and place world actors, and change or delete items on an actor. "create" makes actors with a type of the game system and free system data (the adapter of the system reshapes it where it knows how). "update" changes actors found by id or exact name and merges system data. "delete" removes actors by id for good and needs the actor permission "full". "place" puts world actors as tokens into the active scene. "update-items" and "delete-items" work on the items of one actor by item id; deleting needs "full". "describe" returns what the adapter of the game system says about actor data. Every target is checked before the first write, nothing found is named, and values the system did not store as written are listed as mismatches.
Inputs: action (required), ids, actors, folder, +7 more.
manage-effectsManage active effectsADestructive
Create, change or delete an active effect on an actor, or on an item that actor carries. The effect fields go to Foundry as given, without game system rules; Foundry drops unknown fields, and the result lists every field that was dropped or stored differently. Find effect ids with get-character (effects of the actor) or get-character-entity (effects of an item). An effect that lies on an item is changed there, with parentType "item"; parentType "actor" never touches it. create and update need the actor permission "create and change", delete needs "create, change and delete", which is off by default. Every change is read back.
Inputs: action (required), parentType (required), actorIdentifier (required), effectId, +2 more.
manage-playlistsManage playlistsADestructive
Describe, create, update or delete playlists. describe without playlist lists every playlist (like list-playlists); with playlist it returns that one with its tracks, and a unique part of the name is enough there. create checks every track first and creates the playlist with all tracks in one step. update changes fields of the playlist and of existing tracks; adding or removing tracks is not part of it. delete works by playlist id only, is refused while a scene still uses the playlist, and needs the playlist permission "create, change and delete". For changes a playlist is found by id or exact name (case ignored when unique), never by a part of the name.
Inputs: action (required), fade, mode, name, +8 more.
manage-world-itemsManage itemsADestructive
Items in the world and on actors. "create" makes world items (in a folder by id or path, created when missing and named in the answer), "list" filters world items by type, folder and part of the name, "update" changes world items by id, "add-to-actor" creates items directly on an actor, "remove-from-actor" deletes items of an actor by id or exact name (needs the actor permission "full"; a name that fits several items is refused), and "describe" returns the valid item types and the enumerated values the adapter of the game system reads from its configuration. Item types are checked against the game system before anything is written.
Inputs: action (required), type, items, folder, +5 more.
measure-distanceMeasure a distanceARead-onlyIdempotent
Measure between two tokens or points, optionally via waypoints, in the scene's units and grid spaces, following the grid and the diagonal rule of the world. Token centers count. Works without a drawn canvas.
Inputs: to (required), from (required), via, sceneIdentifier.
move-tokenMove tokenAIdempotent
Put a token at a new position on the active scene (or the scene in sceneIdentifier). x and y are scene pixels of the top left corner of the token; grid, walls and scene bounds are not checked. With animate the token glides there, otherwise it jumps. The answer gives the position Foundry stored.
Inputs: x (required), y (required), tokenId (required), animate, +1 more.
organize-compendiumOrganize compendiumAIdempotent
Sort entries of a compendium into a folder, creating the folder if needed. Entries are named exactly (ignoring case) or by id; names not found and ambiguous names are reported and left where they are. Same lock rules as export-to-compendium.
Inputs: packId (required), entryNames (required), folderName (required), unlockIfNeeded.
pan-cameraPan and zoom the viewAIdempotent
Move the Gamemaster's view to a token or a point and set the zoom; with forEveryone, also pull every player viewing the scene to it (needs "Allow Write Operations"). Needs the drawn canvas in the Gamemaster's browser.
Inputs: x, y, scale, tokenId, +3 more.
pass-cardsPass cardsA
Pass chosen cards from one stack to another, such as from a hand to a pile. Cards are named by id or by exact name within the source stack. Needs the write switch.
Inputs: to (required), from (required), cardIds (required), chatNotification.
pf2e-manage-conditionsManage Pathfinder 2e conditionsADestructive
[Pathfinder 2e only] List, set, increase, decrease, remove or toggle a condition on an actor, with values such as frightened 2 or drained 1. pf2e keeps conditions as items with a value, which toggle-token-condition cannot set or read back; this tool writes through the system's own condition handling and reads the result back. A condition granted by another one (e.g. by grabbed) is removed with its source, not here. persistent-damage needs its damage and is applied on the sheet.
Inputs: action (required), actorIdentifier (required), value, amount, +1 more.
ping-canvasPing a pointA
Show a ping at a token or a point to everyone viewing the scene, optionally pulling their views there. Needs "Allow Write Operations" and the drawn canvas in the Gamemaster's browser.
Inputs: x, y, zoom, style, +3 more.
refresh-scene-thumbRenew scene thumbnailAIdempotent
Create the thumbnail of a scene anew. Needed after a background swap: Foundry keeps showing the old picture in the sidebar until then.
Inputs: sceneIdentifier (required).
remove-actor-ownershipRemove actor ownershipADestructiveIdempotent
Remove the explicit permission a player has on an actor, so the default level of the actor applies again; the answer warns when that default still grants access. To hide an actor completely from a player, assign NONE with assign-actor-ownership instead. Needs confirmRemoval, and confirmBulkOperation when more than one actor or player is affected.
Inputs: actorIdentifier (required), playerIdentifier (required), confirmRemoval, confirmBulkOperation.
remove-combatantsRemove combatantsADestructiveIdempotent
Remove combatants from a combat encounter, by combatant id or token id. Their initiative is lost; the tokens stay on the scene. One unknown id stops everything.
Inputs: dryRun, combatId, tokenIds, combatantIds.
replace-journal-pageReplace the content of a pageADestructiveIdempotent
Replace the whole content of one text page, and optionally rename it, in one write. Content with HTML tags is stored exactly as sent. Plain text becomes paragraphs: a blank line starts a new paragraph, a single line break stays a break, and nothing is removed; Markdown is not converted, and the result says when the text looks like Markdown. Empty content is refused. The page is read back and compared; the result carries its length, not the content. To append instead, use journal-append-page. Needs the journal permission "create and change".
Inputs: pageId (required), journalId (required), newContent (required), newPageName.
request-player-rollsRequest a roll from a playerA
Put a roll button into the chat so a player rolls on their own device. Only that player and a Gamemaster can press it, and it rolls once. Whether the roll is PUBLIC (visible to all players) or PRIVATE (visible to the target player and the Gamemaster only) is a game decision: if the user did not say it, ask "Do you want this to be a PUBLIC roll or a PRIVATE roll?" and wait for the answer, then set isPublic and userConfirmedVisibility. targetPlayer is a player name or a character name. The formula comes from the adapter of the game system; without one, only rollType "custom" with a formula in rollTarget works. A player who is offline gets no request.
Inputs: isPublic (required), rollType (required), rollTarget (required), targetPlayer (required), +3 more.
reset-card-stackReset a card stackADestructiveIdempotent
Reset a stack through Foundry: a deck takes back every card it gave out, from all hands and piles; a hand or pile returns its cards to their decks. Needs the write switch.
Inputs: stackId (required), chatNotification.
reset-roll-tableReturn drawn entries to a roll tableADestructiveIdempotent
Return every drawn entry of a roll table, so all entries can be drawn again.
Inputs: tableId (required).
restore-sceneRestore sceneA
Recreate a scene from a JSON file in the Foundry data directory, for example one pulled out of a world backup, with its walls, tiles, lights, sounds, tokens and levels. The file travels as a file because a scene with walls is too large for the bridge. The scene always gets a new id unless keepId is set, is never active, and never overwrites an existing scene.
Inputs: jsonPath (required), name, index, keepId, +2 more.
roll-actor-checkRoll actor checkA
Roll a check of the game system for an actor, such as ability, skill, save or attack. The formula comes from the game system adapter; in a system without one the answer is SYSTEM_NOT_SUPPORTED and roll-dice rolls a free formula. To let a player roll, use request-player-rolls.
Inputs: actorId (required), rollType (required), flavor, toChat, +3 more.
roll-diceRoll diceA
Roll a free formula in Foundry, in any game system, e.g. "2d6+3" or "4d6kh3". Returns the total and every single die result. With actorId, @ references use that actor's roll data. Nothing is posted unless toChat is true.
Inputs: formula (required), flavor, toChat, actorId, +1 more.
roll-initiativeRoll initiativeADestructive
Roll initiative with the game system's formula: for all combatants, only non player characters, or the combatants named. By default only those without initiative roll. Rolls are posted to the chat only with toChat; a hidden combatant is never posted publicly.
Inputs: scope, toChat, formula, combatId, +3 more.
search-character-itemsSearch character itemsARead-onlyIdempotent
Search inside one actor instead of loading all of it: items whose name or description contains the query, optionally of one item type or category, or actions and effects. Each match has id, name, type, a short plain description and the details the adapter of the game system adds (range, target, level, equipped and so on). Categories come from the adapter; without one there are none, and an unknown category is refused, never ignored.
Inputs: characterIdentifier (required), type, limit, query, +1 more.
search-compendiumSearch compendiumsARead-onlyIdempotent
Search the names of compendium entries across all compendiums except scene compendiums. Every word of the query has to occur in the name; descriptions are not searched. Exact name matches come first. Creature filters need the adapter of the active game system: with packType "Actor" and the creature index they check real values, otherwise they are an estimate from names, and filters the system does not know are reported as ignored. For accurate filtering use list-creatures-by-criteria, and inspect single entries with get-compendium-item.
Inputs: query (required), limit, filters, packType.
search-journalsSearch journalsARead-onlyIdempotent
Find journals by a text, ignoring case, in their names and in the HTML of their text pages. Each hit names the matching pages with a short excerpt, so the page can then be read with list-journals (journalId and pageId). The search runs inside Foundry, in one request.
Inputs: searchQuery (required), searchType.
send-chat-messageSend a chat messageA
Post a message to the Foundry chat as the Gamemaster, or as an actor or token. Without whisperTo and whisperToGamemasters everyone sees it. Recipients are user ids or exact names; an unknown or ambiguous name sends nothing. Content is HTML.
Inputs: content (required), alias, style, flavor, +5 more.
send-notificationSend a notificationA
Show a short notification (plain text, at most 500 characters) in Foundry to everyone or to chosen users, with the Gamemaster named as sender. Users are matched by id or exact name. Users who are not logged in do not get it, and it is not stored. Needs the write switch.
Inputs: message (required), level, users.
set-compendium-lockLock or unlock compendiumAIdempotent
Lock or unlock a compendium. Which ones may be touched follows the module settings: by default every compendium, or only the ones on the release list if it has been filled in.
Inputs: locked (required), packId (required).
set-door-stateOpen, close or lock doorsAIdempotent
Set doors (walls with door "door" or "secret") to open, closed or locked. Every id must be a door of the scene, else nothing changes. Players see the change at once. Needs the level "change" for scenes.
Inputs: state (required), wallIds (required), dryRun, sceneIdentifier.
set-game-pausePause or resume the gameAIdempotent
Pause (paused: true) or resume (paused: false) the game for everyone. Needs the write switch.
Inputs: paused (required).
set-scene-playlistLink a playlist to a sceneADestructiveIdempotent
Link a playlist, and optionally one specific sound, to a scene so it starts when the scene is activated. Pass an empty playlistName to remove the link. The playlist has to exist in the world; use import-from-compendium first if it only exists in a compendium. Names are matched exactly; a sound may also be given as part of its name, as long as only one sound matches.
Inputs: sceneIdentifier (required), soundName, playlistName.
set-targetsSet the Gamemaster's targetsAIdempotent
Replace the Gamemaster's targeted tokens on the viewed scene (ids or names); an empty list clears them. Players see the target marks, and later rolls use them. Needs "Allow Write Operations" and the drawn canvas.
Inputs: tokenIds (required), sceneIdentifier.
set-world-settingChange a world settingADestructiveIdempotent
Change a world setting that is on the list of settings the AI may change (list-settings names the list; it is empty until the Gamemaster decides). Only text, number and true/false settings; the value is checked against choices and range and read back. Needs the write switch.
Inputs: key (required), value (required), namespace (required), dryRun.
shuffle-card-stackShuffle a card stackB
Shuffle the cards of a stack through Foundry. Needs the write switch.
Inputs: stackId (required), chatNotification.
start-combatStart combatAIdempotent
Start a combat encounter in round 1 with the first combatant of the turn order. A running encounter is left as it is and the answer says so.
Inputs: combatId.
switch-sceneSwitch sceneAIdempotent
Activate a scene for every player, by id or name. With optimize_view the view is centred on the map and zoomed so the whole map fits. Players see the switch at once, so this is a change to the world and needs writing to be allowed.
Inputs: scene_identifier (required), optimize_view.
toggle-token-conditionToggle token conditionA
Set or remove a condition (such as prone, poisoned, blinded) on the actor of a token. active true sets it, false removes it, and without active it toggles. conditionId is the id from get-available-conditions or the name. On a linked token the condition lands on the actor and shows on all its tokens; that also needs the actor permission. Removing takes only the effects of that condition. The state is read back. level sets a condition with levels, such as frightened 2 in Pathfinder 2e or pain level 2 in DSA5, and 0 removes it; it needs an adapter for the game system that knows the levels.
Inputs: tokenId (required), conditionId (required), level, active, +1 more.
undo-changeUndo changesADestructive
Undo changes from the change log: one change (changeId), the changes of one tool call (callId, optionally only the last count of them), or without either the latest tool call that is not undone yet. Updates get their recorded fields back, created documents are removed (only if unchanged since), deleted documents are recreated with their old id. Refused as a whole, with the cause, when a change cannot be undone (chat messages, notifications, world time, pause, files, settings), when the permission level for the original change is missing, or when the documents changed since (force: true restores fields anyway, never removes). Every undo is itself logged; undo that entry to redo. Use dryRun first.
Inputs: count, force, callId, dryRun, +1 more.
update-canvas-elementsChange walls, lights and other canvas elementsADestructiveIdempotent
Change up to 200 elements of one type on a scene: each entry is { id, changes }, with Foundry fields and dotted keys such as "config.dim". Wall words as in create-canvas-elements. Every id is checked first; one unknown id changes nothing. Fields already holding the value are not written. Needs the level "change" for scenes.
Inputs: updates (required), elementType (required), dryRun, sceneIdentifier.
update-chat-messageChange a chat messageADestructiveIdempotent
Change the content or flavor of a chat message written by the Gamemaster the bridge runs as. Who sees the message does not change; send a new message for other recipients.
Inputs: messageId (required), flavor, content.
update-combatantUpdate combatantADestructiveIdempotent
Set the initiative of a combatant (null clears it), hide it from players in the tracker, or mark it defeated. The acting combatant keeps its turn when the order changes. defeated is only the tracker flag; toggle-token-condition sets a condition.
Inputs: hidden, tokenId, combatId, defeated, +2 more.
update-documentChange a document of any typeADestructiveIdempotent
Generic fallback: change fields of one document of any type. changes follows Foundry's update rules: keys may be dotted paths, an object merges into the object that is there, lists and other values replace it. A list position in a key ("system.skills.2.value") changes only that entry. replace names keys of changes whose object replaces the stored object instead of merging; remove names paths to delete. The answer is the change as read back from Foundry, and what was stored differently. Ids, ownership, _stats, the type, embedded collections, the flags of this module and what a specialised tool guards (active scene, playback, chat recipients, macro commands) cannot be changed here. Use dryRun first. Prefer update-scene, manage-actors, journal-set-page, update-token, update-roll-table, manage-effects and the other specialised tools where they fit.
Inputs: id, uuid, dryRun, remove, +4 more.
update-quest-journalUpdate a quest journalA
Write progress into a quest journal. Content that contains HTML tags is stored as sent; plain text is escaped and becomes paragraphs, with single line breaks kept. Markdown is not converted. Three ways:
Without pageId and newPageName: a section with a heading for the update type and today's date is added to the progress notes of the first text page (a completion as read-aloud text, everything else as a secret Gamemaster note). completion and failure also set the status in the overview to Completed or Failed.
With pageId: the content is appended to the end of that text page, without a heading.
With newPageName: a new page with a heading and the content as a secret note. Content with its own heading gets no generated one. Pass pageId or newPageName, not both. Every write is read back and compared in full before success is reported; the answer gives the lengths before and after, not the HTML.
Inputs: journalId (required), newContent (required), updateType (required), pageId, +1 more.
update-roll-tableChange a roll tableADestructive
Change the settings and entries of a roll table: name, description, formula, replacement (false means drawn entries do not come again), displayRoll, change entries by id, add entries, remove entries by id. The whole result is checked before anything is written: overlapping ranges are refused, gaps are warnings. Removing entries needs the roll table permission set to full. Entry ids come from get-roll-table.
Inputs: tableId (required), name, formula, results, +5 more.
update-sceneUpdate sceneADestructiveIdempotent
Change an existing scene: name, navigation label, background image or video, background colour, size, folder, navigation, or the linked scene journal. A new background without width and height is measured and the scene takes its size. An empty journalIdentifier removes the link. Every change is read back.
Inputs: sceneIdentifier (required), name, width, height, +7 more.
update-scene-musicSet the music of a sceneADestructiveIdempotent
Set or clear the playlist and the single track a scene plays when it is activated. A parameter left out keeps that field; null or an empty text clears it. playlist_sound alone picks a track of the playlist the scene already has. A new playlist keeps the track only when it belongs to it, otherwise the track is cleared and the result says so; the scene never points at a track outside its playlist. Scene, playlist and track are found by id or exact name (case ignored when unique). Needs the scene permission "create and change".
Inputs: scene_identifier (required), playlist, playlist_sound.
update-tokenUpdate tokenADestructiveIdempotent
Change properties of a token on the map (not of its actor): position, size in grid spaces, rotation, hidden, disposition (-2 secret, -1 hostile, 0 neutral, 1 friendly), displayed name, elevation, rotation lock. Other fields are refused with their names. Every change is read back; values Foundry stored differently come as warnings.
Inputs: tokenId (required), updates (required), sceneIdentifier.
upload-fileUpload a small fileADestructiveIdempotent
Write a small file (at most 512 KiB) into an existing folder of Foundry's data storage, from text or from base64. An existing file is only replaced with overwrite: true. Scripts and HTML are never written, and Foundry accepts only its upload types. Never inside modules, systems or another world. Needs the write switch. Foundry cannot delete files; there is no tool for that.
Inputs: name (required), path (required), text, base64, +2 more.
use-itemUse itemA
Start the use of an item of an actor (a spell, an ability, a consumable) in Foundry and return at once, without waiting for a dialog the Gamemaster may have to confirm. Targets are tokens of the active scene; if one cannot be found exactly, nothing is used. The adapter of the game system decides how the item is used and how consume and spellLevel apply; without one the usual item methods are tried, and failing those a plain chat message is posted. The answer says what was verified (targets, whether the use finished) and what was not (consumption).
Inputs: itemIdentifier (required), actorIdentifier (required), consume, targets, +1 more.
wfrp4e-add-itemsAdd WFRP4e itemsA
[WFRP4e only] Add skills, talents, traits, trappings, careers, weapons, spells and other items to an existing wfrp4e actor. Each name is looked up whole, ignoring case, in the item compendiums, wfrp4e-core first, and the entry is copied in full with a link to it. A specialised skill such as "Entertain (Taunt)" comes from its template "Entertain ()". A name that exists as several types is skipped with all candidates until "type" chooses; "pack" limits the search to compendiums whose id contains it. A name in no compendium becomes a blank item of "type" (trapping without it) and is listed in notFound. "advances" works for skills, "quantity" for gear, "setCurrent" for careers; elsewhere it is ignored with a warning. A skill or career the actor has already is skipped. Everything is read back. Change existing values with wfrp4e-update-actor.
Inputs: actor (required), items (required).
wfrp4e-update-actorUpdate a WFRP4e stat blockAIdempotent
[WFRP4e only] Change the stat block of an existing wfrp4e actor: initial, advances and modifier of characteristics, current and maximum wounds, advances of skills the actor already has, which career is current, movement and biography. Only given fields change; value, bonus and skill totals are recomputed by wfrp4e. Skills and careers match by name ignoring case; one that is missing or there twice is skipped and named in warnings, never guessed. Every value is read back; the answer lists old and new values, the new characteristic totals and anything stored differently. New skills, talents, trappings or careers: wfrp4e-add-items. A new actor: create-actor-from-compendium.
Inputs: actor (required), career, skills, wounds, +3 more.
world-rewrite-pathsMove a path in the whole worldADestructive
After moving files on disk, replace their old path prefix in every document of the world in one step: scenes with tokens, tiles, drawings, notes, sounds, walls, lights and regions; actors with items and effects; items; journals with pages (image pages and images in text); playlists; roll tables; cards; macros. A prefix only matches where a path begins and up to a path boundary, so "Bilder/Token" never touches "Bilder/Tokenringe", and percent-encoded spellings are found too. Runs inside Foundry. Checks the permission of every kind it would change before writing anything. Always run dryRun first and read the report.
Inputs: to (required), from (required), dryRun, collections.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 152 tools
Several tools occupy the same niche: set-scene-playlist and update-scene-music both link a playlist/track to a scene, list-playlists overlaps with manage-playlists' describe mode, and get-compendium-item, get-compendium-entry-full and get-document provide overlapping retrieval. The detailed descriptions help once a tool is chosen, but with 152 tools an agent cannot reliably pick between these near-duplicates.
Names overwhelmingly follow a lowercase hyphenated verb_noun pattern (list-, get-, create-, update-, delete-), which is easy to predict. Deviations such as world-rewrite-paths, journal-link-tags, dnd5e-create-npc and the multi-action manage-* tools break the pattern but are still readable.
152 tools is an extreme count, far past the point where an agent can keep the surface in working memory. Many are redundant with generic fallbacks or with each other; even a broad Foundry adapter would be better scoped to a few dozen cohesive tools.
For a Foundry VTT bridge the surface is unusually thorough: CRUD for nearly every document type, combat, chat, canvas, compendiums, files, playlists, cards, macros, permissions and an undo log. Minor gaps remain (no file deletion, no user or module management, some system-specific workflows only through generic access), but they are workable.
Related MCP Connectors
Connect any AI to your Foundry VTT world: actors, combat, dice, journals, tokens, compendiums.
Official remote MCP server for Archivist AI TTRPG campaign memory: characters, sessions, and more.
Read and update your SekkeiFlow life boards, counters and AI coach from any MCP client.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceConnects Claude Desktop to Foundry VTT for AI-powered campaign management, enabling natural language interaction with game data including quest creation, character management, compendium searches, and dice rolling. Provides 20 MCP tools for seamless integration between Claude and your tabletop RPG sessions.87MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with Foundry Virtual Tabletop, supporting reading world data, managing combat, rolling dice, and updating actor attributes via a sidecar architecture.ISC
- AlicenseAqualityCmaintenanceEnables D&D Beyond integrations through MCP by reading character sheets, monster statblocks, and campaign rosters, plus streaming live game-log dice rolls with optional write tools for HP and conditions.10MIT
- FlicenseNot gradedqualityBmaintenanceEnables MCP clients to interact with Foundry Virtual Tabletop worlds via a permissioned Windows host and GM-authorized browser companion, including document management, asset uploads, journal sessions, and background intelligence.-