FoundryVTT MCP Server Documentation - v0.9.2
    Preparing search index...

    Class FoundryClient

    Client for communicating with FoundryVTT instances

    This class provides methods for interacting with FoundryVTT through both REST API and WebSocket connections. It supports dice rolling, actor/item searching, scene management, and real-time updates.

    FoundryClient

    const client = new FoundryClient({
      baseUrl: 'http://localhost:30000',
      apiKey: 'your-api-key'
    });

    await client.connect();
    const actors = await client.searchActors({ query: 'Hero' });
    const diceResult = await client.rollDice('1d20+5', 'Attack roll');
    Index

    Constructors

    constructor

    Methods

    testConnection disconnect isConnected connect sendMessage onMessage rollDice searchActors getActor searchItems getCurrentScene getScene getWorldInfo get post put delete

    Constructors

    Methods

    • Tests the connection to FoundryVTT server

      Returns Promise<boolean>

      Promise that resolves to true if connection is successful

      If connection fails

      try {
        const isConnected = await client.testConnection();
        console.log('Connected:', isConnected);
      } catch (error) {
        console.error('Connection failed:', error);
      }

    • Disconnects from FoundryVTT server

      Closes WebSocket connection and resets connection state.

      Returns Promise<void>

      Promise that resolves when disconnection is complete

      await client.disconnect();
      console.log('Disconnected from FoundryVTT');

    • Checks if client is currently connected to FoundryVTT

      Returns boolean

      True if connected, false otherwise

      if (client.isConnected()) {
        console.log('Client is connected');
      }

    • Establishes connection to FoundryVTT server

      Uses either REST API or WebSocket connection based on configuration.

      Returns Promise<void>

      Promise that resolves when connection is established

      If connection fails

      await client.connect();
      console.log('Connected to FoundryVTT');

    • Sends a message via WebSocket connection

      Parameters

      • message: any

        Message object to send

      Returns void

      client.sendMessage({
        type: 'chat',
        content: 'Hello from MCP!'
      });

    • Registers a message handler for specific WebSocket message types

      Parameters

      • type: string

        Message type to handle

      • handler: Function

        Function to call when message is received

      Returns void

      client.onMessage('combatUpdate', (data) => {
        console.log('Combat updated:', data);
      });

    • Rolls dice using FoundryVTT's dice system

      Parameters

      • formula: string

        Dice formula in standard notation (e.g., '1d20+5', '3d6')

      • Optionalreason: string

        Optional reason for the roll

      Returns Promise<DiceRoll>

      Promise resolving to dice roll result

      const result = await client.rollDice('1d20+5', 'Attack roll');
      console.log(`Rolled ${result.total} (${result.breakdown})`);

    • Retrieves detailed information about a specific actor

      Parameters

      • actorId: string

        The ID of the actor to retrieve

      Returns Promise<FoundryActor>

      Promise resolving to actor data

      If actor is not found

      const actor = await client.getActor('actor-id-123');
      console.log(`Actor: ${actor.name} (${actor.type})`);

    • Retrieves the current active scene or a specific scene by ID

      Parameters

      • OptionalsceneId: string

        Optional scene ID. If not provided, returns current scene

      Returns Promise<FoundryScene>

      Promise resolving to scene data

      If scene is not found

      const currentScene = await client.getCurrentScene();
      console.log(`Current scene: ${currentScene.name}`);

      const specificScene = await client.getCurrentScene('scene-id-123');

    • Retrieves a specific scene by ID

      Parameters

      • sceneId: string

        The ID of the scene to retrieve

      Returns Promise<FoundryScene>

      Promise resolving to scene data

      const scene = await client.getScene('scene-id-123');
      console.log(`Scene: ${scene.name} (${scene.width}x${scene.height})`);

    • Retrieves information about the current world

      Returns Promise<FoundryWorld>

      Promise resolving to world information

      If world information cannot be retrieved

      const world = await client.getWorldInfo();
      console.log(`World: ${world.title} (${world.system})`);

    • Makes a GET request to the FoundryVTT server

      Parameters

      • url: string

        The URL path to request

      • Optionalconfig: any

        Optional axios request configuration

      Returns Promise<any>

      Promise resolving to the response

      const response = await client.get('/api/diagnostics/health');
      console.log(response.data);

    post

    • post(url: string, data?: any, config?: any): Promise<any>

      Makes a POST request to the FoundryVTT server

      Parameters

      • url: string

        The URL path to request

      • Optionaldata: any

        The data to send in the request body

      • Optionalconfig: any

        Optional axios request configuration

      Returns Promise<any>

      Promise resolving to the response

      const response = await client.post('/api/dice/roll', { formula: '1d20' });
      console.log(response.data);

    • Makes a PUT request to the FoundryVTT server

      Parameters

      • url: string

        The URL path to request

      • Optionaldata: any

        The data to send in the request body

      • Optionalconfig: any

        Optional axios request configuration

      Returns Promise<any>

      Promise resolving to the response

    • Makes a DELETE request to the FoundryVTT server

      Parameters

      • url: string

        The URL path to request

      • Optionalconfig: any

        Optional axios request configuration

      Returns Promise<any>

      Promise resolving to the response

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods