foundry-cli

CLI and MCP server for managing Foundry VTT world content via Socket.io. Targets Foundry v14.

Scope

This tool manages the journal layer of a Foundry world: journal entries, their categories, and their pages. It also lists actors. It is intentionally narrow — no scene management, no compendium access, no system-specific mechanics.

The primary use case is AI-assisted world-building: an LLM writes lore entries via the MCP server while a GM reviews them in the Foundry UI in real time.

Setup

Requirements: Python 3.12+, uv, a running Foundry v14 instance with an active world.

git clone <repo>
cd foundry-cli
cp .env.example .env   # fill in credentials

.env keys:

Key	Description
FOUNDRY_URL	Base URL of the Foundry instance, e.g. https://foundry.example.com
FOUNDRY_BASIC_USER	HTTP Basic Auth username (if Foundry is behind a proxy)
FOUNDRY_BASIC_PASS	HTTP Basic Auth password
FOUNDRY_WORLD	The world name that must be active
FOUNDRY_GM_USER	Foundry user to authenticate as (must have GM role)
FOUNDRY_GM_PASSWORD	Password for that user

CLI usage

uv run python foundry.py [COMMAND] --help

Actors

foundry actor list [--json]

Journals

foundry journal list [--json]
foundry journal upsert --title NAME [--folder FOLDER] [--public]
foundry journal delete --title NAME

Categories

Categories are named tabs that group pages within a journal. Create them before assigning pages.

foundry journal category list   --journal NAME [--json]
foundry journal category upsert --journal NAME --name NAME
foundry journal category delete --journal NAME --name NAME

Pages

foundry journal page list    --journal NAME [--json]
foundry journal page upsert  --journal NAME --title NAME
                             [--category NAME] [--level 1-6]
                             [--before TITLE | --after TITLE]
                             [--public]
                             [--content HTML | --content-file PATH | stdin]
foundry journal page reorder --journal NAME   # titles from stdin, one per line
foundry journal page delete  --journal NAME --title NAME

Content input — exactly one of:

• --content '<p>HTML</p>' — inline string
• --content-file path/to/page.html — read from file
• stdin — pipe HTML directly: cat page.html | foundry journal page upsert ...

Positioning — --before TITLE / --after TITLE insert the page relative to an existing page within the same category. All pages in the category are reindexed with clean sort values.

Level — controls sidebar indentation (1 = top-level, 2 = indented beneath the preceding level-1 page).

--public — sets OBSERVER ownership so players can see the entry/page. Default is INHERIT (follows the parent journal).

All upsert operations are idempotent — matched by name, safe to re-run.

Example workflow

# Create journal and categories
foundry journal upsert --title "Ravens — Lore"
foundry journal category upsert --journal "Ravens — Lore" --name "Settlements"
foundry journal category upsert --journal "Ravens — Lore" --name "NPCs"

# Add pages
echo "<p>A walled city on the northern coast.</p>" | \
  foundry journal page upsert \
    --journal "Ravens — Lore" --title "Thornwall" \
    --category "Settlements" --level 1

echo "<p>The merchant district.</p>" | \
  foundry journal page upsert \
    --journal "Ravens — Lore" --title "Thornwall — Docks Quarter" \
    --category "Settlements" --level 2 --after "Thornwall"

# Reorder pages
printf "Thornwall\nThornwall — Docks Quarter\nThornwall — Temple Quarter\n" | \
  foundry journal page reorder --journal "Ravens — Lore"

MCP server

The MCP server exposes the same operations as tools so LLMs can manage journal content directly.

uv run python foundry_mcp.py

Register in an MCP client config:

{
  "mcpServers": {
    "foundry": {
      "command": "uv",
      "args": ["run", "python", "/path/to/foundry_mcp.py"]
    }
  }
}

Available tools: actor_list, journal_list, journal_upsert, journal_delete, category_list, category_upsert, category_delete, page_list, page_upsert, page_reorder, page_delete.

Testing

Tests run against a real Foundry instance spun up via Docker Compose. The test fixture starts the container, waits for the world to become active, then runs against it.

uv run pytest

The Docker environment lives in docker/. Tests create journals with a _pytest_ prefix and clean up on teardown.

Architecture vs foundryvtt-mcp

foundryvtt-mcp is a JavaScript MCP server that runs inside Foundry as a module, calling the Foundry API directly from within the same process.

This project takes the opposite approach:

	foundry-cli	foundryvtt-mcp
Runtime	External Python process	Foundry module (in-process JS)
Protocol	Socket.io modifyDocument	Direct Foundry API calls
Install footprint	Nothing installed in Foundry	Requires a Foundry module
Interface	CLI + MCP server	MCP server only
Scope	Journals and actors	Broader (scenes, actors, items, …)

Why Socket.io instead of a Foundry module?

• No Foundry module to maintain across Foundry version updates — the Socket.io wire protocol is stable.
• Works with a remote or hosted Foundry instance without SSH or file system access.
• The CLI is useful on its own for scripting and automation, independent of any AI tooling.

Trade-offs: The Socket.io modifyDocument API is not officially documented for external use, so it may break across major Foundry versions. Operations are limited to what that API surface exposes — complex queries or compendium access require a different approach.