mcp-xiv-clientstructs

An MCP server that indexes the FFXIVClientStructs C# library and exposes it as searchable tools for any MCP-compatible AI assistant. Useful when writing Dalamud plugins.

Tools

Environment variables

Both are required. The server will exit on startup if either is missing.

Setup

1. Clone FFXIVClientStructs somewhere:

git clone https://github.com/aers/FFXIVClientStructs.git /path/to/ffxiv_clientstructs_repo

2. Install and build:

npm install
npm run build

3. Add to your MCP host's config:

{
  "mcpServers": {
    "ffxiv-structs": {
      "command": "node",
      "args": ["/path/to/mcp-xiv-clientstructs/dist/index.js"],
      "env": {
        "FFXIV_STRUCTS_REPO": "/path/to/ffxiv_clientstructs_repo",
        "FFXIV_STRUCTS_INDEX": "/path/to/mcp-xiv-clientstructs/index.json"
      }
    }
  }
}

On first start the index is built automatically (~2–5s). Subsequent starts load the cached index instantly unless the repo SHA has changed.

Keeping up to date

On every start, the server compares the repo's current git SHA against the cached index. If they differ (e.g. because you pulled externally), it rebuilds automatically.

The refresh tool does this in one step without a restart: it runs git pull on the repo and rebuilds the index if the SHA changed. Useful to call after a game patch.