ninjos-foundry-mcp
Generates battle maps and location images in a consistent style through Google's Gemini API, using the user's own Google account and Generative Language API key.
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., "@ninjos-foundry-mcp What scenes are in the current Foundry world?"
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
Let Claude and other AI assistants prepare your Foundry VTT world with you: scenes, journals, NPCs, compendiums and more, always within the permissions you set.
(Scroll down for the German version / Weiter unten auf Deutsch)
🇬🇧 English
Imagine writing to Claude: "Set up a harbour tavern for tonight, with an innkeeper, two shady guests and a journal for each of them about what they know." And a few moments later, exactly that is waiting in your Foundry world. Ninjo's Foundry MCP makes this possible. It connects Claude and other AI assistants that speak the Model Context Protocol to your world, so they can read, look things up and prepare things for you there.
You always decide how far that goes. Out of the box the assistant may create and change things, but not delete anything, and everything it does is recorded and can usually be taken back.
What you can do with it
Preparation is where it helps most. The assistant creates scenes, sorts them into folders, attaches journals to them, and can even look at a scene as a picture with grid and tokens to understand what is on it. It writes journals and whole quest chains, links them to the right NPCs, and later finds whatever is written somewhere in your world. It builds characters and NPCs from scratch or from your compendiums, with effects and conditions, and hands them to a player if you like.
It helps on the canvas too: with walls and doors, lights, sounds, regions, tiles and drawings, with measuring distances and with finding a path around walls. During the game it can set up encounters, roll initiative, advance turns, make rolls and system checks, and ask individual players for a roll. Chat, roll tables, macros, card stacks, playlists, world time and your files are part of it as well.
Once a chapter of your campaign has been played, the assistant can move it into a compendium, sort it there and lock it. Your world stays tidy, and nothing gets lost.
With a Gemini key of your own it also paints battle maps and location pictures in a consistent style, matched to the scene pictures you already have, and fixes details on request. Every image is a paid request on your own Google account. Give the key a spending limit, restrict it to the Generative Language API, and put it only into the MCP server entry on your PC, never into Foundry. The installation guide shows how.
The core tools work in every game system. For D&D 5e, Pathfinder 2e, Das Schwarze Auge 5, Warhammer Fantasy Roleplay 4e, the Cosmere RPG and Mongoose Traveller 2e, the module also knows the particulars of the system.
You stay in control
The module works for you as the GM only. Players get no access to it, not even through detours.
A master switch in the settings allows or forbids every change, and when it is off, the assistant can only read. Below it you decide for each kind of document how far the assistant may go: read only, create and change, or delete as well. Deleting is switched off everywhere until you explicitly allow it for a kind of document, because it is the one change that cannot be taken back. Running macros is off by default too.
Every change goes into a log. There you can read what the assistant did and undo single steps or a whole request, wherever that is possible.
Two parts that belong together
The Foundry MCP has two parts, and you need both. The module runs in Foundry, in your browser, and carries out the requests in your world. The server runs on your PC next to Claude and passes the tools on to the assistant. The two only talk to each other on your own computer, and nothing can be reached from outside. If either part is missing, simply nothing happens: Foundry shows the connection as disconnected, or Claude sees no tools.
Setting it up
First the module. In Foundry, open the Add-on Modules tab, click Install Module and search for Ninjo's Foundry MCP. You can also use this manifest URL:
https://github.com/Niclasp1501/ninjos-foundry-mcp/releases/latest/download/module.jsonThen enable it in your world.
Then the server on your PC. Download the server package
ninjos-foundry-mcp-server-…-win32-x64.zip from the
releases page, unpack it
and double click setup.cmd. Setup registers the server with Claude Desktop and takes over an
existing installation along with your settings. You need neither Node.js nor administrator
rights for this. Then quit Claude Desktop completely and start it again.
Finally, load your world. Open your world as the GM, and the module connects to the server. To try it out, just ask Claude which world is open in Foundry.
For Claude Code, other clients and troubleshooting there is a detailed installation guide.
You need Foundry VTT v13 or v14, a Windows PC, and Claude Desktop, Claude Code or another program that speaks MCP. Foundry has to run in a browser on the same PC as the server. There is no package for the Mac yet.
Coming from an older version
With version 14.2609.4, the module and the server were rewritten from the ground up. Tool names, your world's settings, permissions and the manifest URL stayed the same, so Foundry offers you the update as usual. You do have to set up the server on your PC once with the new server package, as described above. As long as an old server is still connected, a notice in Foundry reminds you.
Related MCP server: foundry-cli
🇩🇪 Deutsch
Stell dir vor, du schreibst Claude: „Leg mir für heute Abend eine Hafentaverne an, mit einem Wirt, zwei zwielichtigen Gästen und je einem Journal dazu, was sie wissen." Und ein paar Momente später steht genau das in deiner Foundry-Welt. Ninjo's Foundry MCP macht das möglich. Es verbindet Claude und andere KI-Assistenten, die das Model Context Protocol sprechen, mit deiner Welt, sodass sie dort lesen, nachschlagen und für dich vorbereiten können.
Dabei entscheidest immer du, wie weit das geht. Ab Werk darf der Assistent anlegen und ändern, aber nichts löschen, und alles, was er tut, wird festgehalten und lässt sich in den meisten Fällen zurücknehmen.
Was du damit machen kannst
Die Vorbereitung ist der größte Gewinn. Der Assistent legt Szenen an, sortiert sie in Ordner, hängt Journale daran und kann sich eine Szene sogar als Bild mit Gitter und Figuren ansehen, um zu verstehen, was darauf liegt. Er schreibt Journale und ganze Questreihen, verknüpft sie mit den passenden NSC und findet später wieder, was irgendwo in deiner Welt steht. Figuren und NSC baut er von Grund auf oder aus deinen Kompendien, samt Effekten und Zuständen, und gibt sie auf Wunsch einem Spieler.
Auch auf dem Spielfeld hilft er mit: bei Wänden und Türen, Lichtern, Klängen, Regionen, Kacheln und Zeichnungen, beim Messen von Entfernungen und beim Finden eines Weges um Wände herum. Während des Spiels kann er Begegnungen anlegen, die Initiative würfeln, Züge weiterschalten, Würfe und Proben des Systems ausführen und einzelne Spieler um einen Wurf bitten. Chat, Zufallstabellen, Makros, Kartenstapel, Wiedergabelisten, die Weltzeit und deine Dateien gehören ebenfalls dazu.
Wenn ein Abschnitt eurer Kampagne fertig gespielt ist, räumt der Assistent ihn in ein Kompendium, sortiert ihn dort und sperrt es. So bleibt deine Welt übersichtlich, ohne dass etwas verloren geht.
Mit einem eigenen Gemini-Schlüssel malt er außerdem Battlemaps und Ortsbilder in einem einheitlichen Stil, passend zu den Szenenbildern, die du schon hast, und bessert auf Wunsch Details nach. Jedes Bild ist eine bezahlte Anfrage über deinen eigenen Google-Zugang. Gib dem Schlüssel ein Ausgabenlimit, beschränke ihn auf die Generative Language API und trag ihn nur beim MCP-Server auf deinem PC ein, nie in Foundry. Wie das geht, steht in der Installationsanleitung.
Die Grundwerkzeuge laufen in jedem Spielsystem. Für D&D 5e, Pathfinder 2e, Das Schwarze Auge 5, Warhammer Fantasy Roleplay 4e, das Cosmere RPG und Mongoose Traveller 2e kennt das Modul außerdem die Eigenheiten des Systems.
Du behältst die Kontrolle
Das Modul arbeitet nur für dich als Spielleiter. Spieler bekommen keinen Zugriff darauf, auch nicht über Umwege.
Ein Hauptschalter in den Einstellungen erlaubt oder verbietet jede Änderung, und steht er auf aus, kann der Assistent nur lesen. Darunter legst du für jede Art von Dokument fest, wie weit er gehen darf: nur lesen, anlegen und ändern, oder zusätzlich löschen. Löschen ist dabei überall abgeschaltet, bis du es für eine Dokumentart ausdrücklich erlaubst, denn es ist die eine Änderung, die sich nicht zurücknehmen lässt. Makros ausführen darf der Assistent ab Werk ebenfalls nicht.
Jede Änderung landet in einem Protokoll. Dort kannst du nachlesen, was der Assistent getan hat, und einzelne Schritte oder einen ganzen Auftrag wieder rückgängig machen, wo das möglich ist.
Zwei Teile, die zusammengehören
Der Foundry MCP besteht aus zwei Teilen, und du brauchst beide. Das Modul läuft in Foundry, in deinem Browser, und führt die Aufträge in deiner Welt aus. Der Server läuft auf deinem PC neben Claude und reicht die Werkzeuge an den Assistenten weiter. Beide sprechen nur auf deinem eigenen Rechner miteinander, von außen ist nichts erreichbar. Fehlt einer der beiden Teile, passiert einfach nichts: Foundry zeigt die Verbindung als getrennt, oder Claude sieht keine Werkzeuge.
Einrichten
Zuerst das Modul. Öffne in Foundry den Reiter Add-on-Module, klicke auf Modul installieren und suche nach Ninjo's Foundry MCP. Du kannst auch diese Manifest-Adresse verwenden:
https://github.com/Niclasp1501/ninjos-foundry-mcp/releases/latest/download/module.jsonDanach aktivierst du es in deiner Welt.
Dann der Server auf deinem PC. Lade auf der
Seite mit den Veröffentlichungen
das Serverpaket ninjos-foundry-mcp-server-…-win32-x64.zip herunter, entpacke es und starte
setup.cmd mit einem Doppelklick. Die Einrichtung meldet den Server bei Claude Desktop an und
übernimmt eine vorhandene Installation samt deiner Einstellungen. Du brauchst dafür weder Node.js
noch Administratorrechte. Beende Claude Desktop danach ganz und starte es neu.
Zum Schluss die Welt laden. Öffne deine Welt als Spielleiter, und das Modul verbindet sich mit dem Server. Frag Claude zum Ausprobieren einfach, welche Welt gerade in Foundry geöffnet ist.
Für Claude Code, andere Programme und die Fehlersuche gibt es eine ausführliche Installationsanleitung.
Du brauchst Foundry VTT v13 oder v14, einen Windows-PC und Claude Desktop, Claude Code oder ein anderes Programm, das MCP spricht. Foundry muss dabei im Browser auf demselben PC laufen wie der Server. Ein Paket für den Mac gibt es noch nicht.
Wenn du von einer älteren Version kommst
Mit Version 14.2609.4 sind Modul und Server von Grund auf neu geschrieben worden. Werkzeugnamen, Einstellungen deiner Welt, Rechte und die Manifest-Adresse sind gleich geblieben, deshalb bietet Foundry dir das Update ganz normal an. Den Server auf deinem PC musst du allerdings einmal mit dem neuen Serverpaket einrichten, wie oben beschrieben. Solange noch ein alter Server verbunden ist, erinnert dich ein Hinweis in Foundry daran.
Support / Unterstützen
The modules are free and stay free. If they help your group, you can support my work on Patreon and get premium add-ons in return. What you get there is on the premium page of Ninjo's Forge.
Die Module sind kostenlos und bleiben es. Wenn sie deiner Runde helfen, kannst du meine Arbeit auf Patreon unterstützen und bekommst Premium-Erweiterungen dazu. Was es dort gibt, steht auf der Premium-Seite der Forge.
Thank you to the Legends who support these modules on Patreon at the highest tier: AaronShep.
Danke an die Legends, die diese Module auf Patreon in der höchsten Stufe unterstützen: AaronShep.
Technical notes
The Foundry module ninjos-foundry-mcp runs 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. Only a Gamemaster connects. The PC server is started by your MCP client; 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, and a server and a module one version apart still work together.
Every change goes through one permission check in the module, whichever tool asks for it. The
permission levels exist for scenes, playlists, journals, roll tables, actors, folders,
compendiums and macros; the default is create and change. A macro on somebody's hotbar is only
deleted after the assistant has asked. Items, card stacks, chat messages and combat encounters
have no level yet: they can be created and changed while the write switch is
on, and deleting them is refused. Destructive tools can additionally require a one-time
confirmation with a dry run first ("Confirm destructive tools"). list-changes shows the change
log, and undo-change reverts an entry or a whole call where that is possible.
Supported MCP clients are Claude Desktop (including the Store edition), Claude Code, Cursor and any
client that starts MCP servers through command and args. The server runs on Windows 10 and 11.
Without an adapter for the game system, a tool that needs one says so.
The full installation guide, including updating and uninstalling, is in docs/INSTALLATION.en.md (German: docs/INSTALLATION.md).
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) 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, +21 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
The descriptions are unusually explicit and often point to the preferred specialized tool, but the set contains several close clusters (list-compendiums/list-compendium-packs/list-compendium-entries, get-compendium-item/get-compendium-entry-full, set-scene-playlist/update-scene-music/control-playlist) and generic CRUD fallbacks that overlap with nearly every specialized tool. An agent can usually disambiguate, but misselection is a real risk.
Most tools follow snake_case verb_noun patterns, but there are notable inconsistencies: the journal family is noun-first (journal-create, journal-delete) while scene and roll-table tools are verb-first, and system-specific tools mix prefixes (dnd5e-create-npc) with mid-name system markers (create-dsa5-character-from-archetype). Still readable, but not a single predictable convention.
152 tools is a very heavy surface. The Foundry domain is broad, but generic CRUD fallbacks, multiple compendium-listing variants, and system-specific duplicates inflate the count well beyond what an agent can comfortably navigate.
The surface covers nearly every Foundry subsystem with full lifecycles: scenes, journals, actors, items, combat, chat, cards, roll tables, playlists, compendiums, canvas elements, tokens, and files. Residual gaps such as macro update/delete or folder creation are covered by generic document tools, so there are no dead ends.
Maintenance
Related MCP Connectors
Connect any AI to your Foundry VTT world: actors, combat, dice, journals, tokens, compendiums.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
Official remote MCP server for Archivist AI TTRPG campaign memory: characters, sessions, and more.
Create AI Characters and generate their DM and comment replies from any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA Model Context Protocol server that integrates with FoundryVTT, allowing AI assistants to interact with tabletop gaming sessions through natural language to query actors, roll dice, generate content, and manage game worlds.243 npm35MIT
- FlicenseAqualityDmaintenanceMCP server for managing Foundry VTT journal content (entries, categories, pages) and listing actors, enabling AI-assisted world-building via natural language commands.11-
- 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
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to act as co-GMs and GM assistants within Foundry Virtual Tabletop, providing tools for game mechanics, actors, tokens, combat, canvas placeables, scenes, and world management.243 npmMIT