Catalyst MCP for FiveM

An MCP server that lets Claude, or any MCP client, build GTA V particle effects (.ypt) for FiveM. You describe the effect, it finds a vanilla one to start from, edits it and gives you a dictionary you can stream. No editor window, no running game.

Unofficial. Not affiliated with Rockstar Games or Cfx.re. See NOTICE.md.

Contents: What a session looks like · Quick start · Tools · How it works · Troubleshooting · License

What a session looks like

"Make me confetti in red and gold for a halftime show."

The assistant searches the effects in your own GTA V install:

ptfx_vanilla_search  query: "confetti"

5 hits
  scr_man_col         scr_man_col_confetti         2 emitters
  scr_man_col         scr_man_col_confetti_gold    2 emitters
  scr_sb_col          scr_sb_col_confetti          1 emitter
  scr_sb_col          scr_sb_col_confetti_gold     1 emitter
  scr_xs_celebration  scr_xs_confetti_burst        1 emitter

picks one, copies it into a new dictionary and makes a second colour from it:

ptfx_merge   scr_xs_celebration / scr_xs_confetti_burst  ->  my_fx / my_confetti_red
ptfx_edit    duplicated effect my_confetti_red -> my_confetti_gold
             tint my_confetti_red min [200,20,30]
             tint my_confetti_gold min [255,190,40]

then builds the file and reads it back to check it:

ptfx_pack    my_fx.ypt   2,384 bytes   read back: identical, 0 differences
ptfx_install resources/my_halftime/stream/my_fx.ypt

and you play it in game:

RequestNamedPtfxAsset("my_fx")
while not HasNamedPtfxAssetLoaded("my_fx") do Wait(0) end
UseParticleFxAssetNextCall("my_fx")
StartParticleFxNonLoopedAtCoord("my_confetti_gold", x, y, z, 0.0, 0.0, 0.0, 1.0, false, false, false)

These are real results from a run against a Legacy install, shortened for reading.

Related MCP server: Expose

Quick start

You need Windows, GTA V Legacy (Steam, Epic or Rockstar Games Launcher), Node.js 20+ and the .NET 8 SDK.

git clone --recurse-submodules https://github.com/Geckomacabre/Catalyst-MCP-Server-for-FiveM.git
cd Catalyst-MCP-Server-for-FiveM
npm install
npm run build
npm run build:helper

Add it to Claude Code:

claude mcp add catalyst-fivem -s user -- node C:/path/to/Catalyst-MCP-Server-for-FiveM/dist/index.js

Then ask for an effect. The first time, the assistant runs ptfx_vanilla_index. This takes a few minutes: it reads the effects out of your game files and caches them locally.

Add this to the client's MCP config:

{
  "mcpServers": {
    "catalyst-fivem": {
      "command": "node",
      "args": ["C:/path/to/Catalyst-MCP-Server-for-FiveM/dist/index.js"]
    }
  }
}

The GTA V folder is found automatically (from the registry and the usual install folders). If it isn't, set GTAV_PATH, or pass game to ptfx_vanilla_index.

Tools

• ptfx_vanilla_index: takes a few minutes, once. When an effect exists in several archives it keeps the newest copy (DLC, then patch, then base; ptfx_hi first).

• ptfx_info: duration, loops and emitter/particle pairs per effect; spawn rate, life and domains per emitter; shader, behaviours, textures and colour keys per particle. With detail it lists every keyframed property.

• ptfx_merge: everything the chosen effects use comes with them: emitters, particles, chained effects, textures and models. Effects can be renamed on the way in.

• ptfx_edit operations:

  • set: a single value

  • keys: replace a keyframed property's keys

  • scale: multiply a value or keys

  • rename, duplicate, delete

  • tint: an effect's colour tint

  • texture: your own .dds, or one of the game's core textures

  • dict_name: rename the dictionary

• ptfx_pack: the built file is turned back into XML and compared rule by rule, so you know it is what you asked for.

• catalyst_open: the same as double-clicking the file. Use it to preview; Catalyst is also the way to export for GTA V Enhanced.

How it works

The server is TypeScript (src/). A small .NET helper (helper/) built on CodeWalker.Core converts .ypt files to and from XML and reads the game's archives. All editing happens on that XML, and the server writes it out byte for byte the way CodeWalker does.

• The archive keys come from your own GTA5.exe, as CodeWalker does it. Nothing is written into the game folder, and no game files are included in this repo.

• Builds are Legacy (gen8), the format FiveM streams. For Enhanced (gen9), open the result in Catalyst and export from there.

• Dictionary entries are stored sorted by name hash, so builds are compared by rule name, not position.

• RefCount is 1 + the number of references, matching Rockstar's files.

• KeyframeTime.y is 1 / (t − t_prev).

• Floats are float32.

• Textures with ExternalReference=1 come from the game's core effects, by name.

Troubleshooting

• GTA V (Legacy) folder not found: set GTAV_PATH to the folder that contains GTA5.exe.

• that is GTA V Enhanced: the index reads Legacy, which is what FiveM runs. Point it at a Legacy install.

• ptfx-helper not found: run npm run build:helper. It needs the .NET 8 SDK, not only the runtime.

• no vanilla index yet: run ptfx_vanilla_index once. The assistant usually does this on its own.

• not a FiveM resource folder: ptfx_install wants the resource's own folder, the one with fxmanifest.lua in it.

• An empty vendor/codewalker folder: you cloned without submodules. Run git submodule update --init.

• The effect doesn't show in game: the name in RequestNamedPtfxAsset must match the .ypt file name, and the resource must be started.

Tests

npm test

The test needs one vanilla .ypt: build the index first, or point PTFX_TEST_YPT at one. It checks the XML round trip, a vanilla rebuild, merge, edit, pack and the MCP protocol.

License

GPL-3.0. CodeWalker is MIT; see NOTICE.md.