utmt-mcp

中文 · English

通过 UndertaleModCli 读取和导出 GameMaker 数据文件（.win、.ios、.droid、.unx）的 MCP 服务器。

专为 LLM 工具调用而设计 —— 所有输出均为干净的 JSON，实体按名称查找。

跨平台 —— 支持 Windows、macOS、Linux。UndertaleModCli 为这三个平台都提供了官方构建。

快速开始

npx utmt-mcp

或全局安装：

npm install -g utmt-mcp
utmt-mcp

Related MCP server: GMS2 MCP Server

环境要求

• Node.js 18+

• .NET 运行时（UndertaleModCli 需要）

• UndertaleModCli —— 加入 PATH，或通过环境变量 / 工具参数指定

安装 UndertaleModCli

从 GitHub Releases 下载对应平台的构建包，解压后任选一种方式：

• 把可执行文件加入系统 PATH，或

• 将 UTMT_CLI_PATH 环境变量设置为可执行文件的完整路径

在 Windows 上 CLI 二进制文件带 Windows 可执行文件后缀；macOS 和 Linux 上没有后缀。其余用法完全一致。

配置

环境变量

MCP 客户端配置

在 MCP 客户端中（如 Claude Desktop、Cursor、Claude Code 等）：

{
  "mcpServers": {
    "utmt": {
      "command": "npx",
      "args": ["-y", "utmt-mcp"],
      "env": {
        "UTMT_CLI_PATH": "/path/to/UndertaleModCli"
      }
    }
  }
}

或者在每次工具调用时显式传入 CLI 路径（无需环境变量）：

{
  "mcpServers": {
    "utmt": {
      "command": "npx",
      "args": ["-y", "utmt-mcp"]
    }
  }
}

工具

utmt-info

获取 GameMaker 数据文件的概览信息。返回 JSON，包含项目名称、GM 版本、isYYC 标志和各类资源数量。

参数：

• dataFilePath（必填）— 数据文件路径

• cliPath（可选）— UndertaleModCli 路径

utmt-list-entities

列出指定类型的实体。返回 JSON 数组，包含索引、名称和简要属性。

参数：

• dataFilePath（必填）

• entityType（必填）— 可选值：sprites、sounds、scripts、code、rooms、gameobjects、fonts、backgrounds、paths、shaders、strings、timelines、embeddedtextures、embeddedaudio、extensions、sequences、particlesystems

• filter（可选）— 不区分大小写的名称过滤

• offset（可选）— 分页偏移（默认：0）

• limit（可选）— 最大返回数，1-500（默认：50）

• cliPath（可选）

utmt-get-entity

获取单个实体的详细信息。返回 JSON，包含所有属性。

参数：

• dataFilePath（必填）

• entityType（必填）— 可选值：sprite、sound、script、code、room、gameobject、font、string、generalinfo

• name（必填）— 实体名称（string 类型用数字索引；generalinfo 忽略此参数）

• cliPath（可选）

utmt-decompile-code

将代码条目反编译回 GML 源码。YYC 编译的游戏不可用。

参数：

• dataFilePath（必填）

• codeName（必填）— 代码条目名称（如 gml_Script_myFunction）

• cliPath（可选）

utmt-export-entity

将单个实体导出到磁盘。

参数：

• dataFilePath（必填）

• entityType（必填）— 可选值：sprite、sound、code、embeddedtexture

• name（必填）— 实体名称（embeddedtexture 用数字索引）

• outputPath（必填）— 输出文件或目录路径

• cliPath（可选）

导出格式：

• sprite → 输出目录中的 PNG 帧

• sound → .ogg 或 .wav 文件

• code → 反编译后的 .gml 文件

• embeddedtexture → PNG 文件

utmt-search

跨所有类型按名称模式搜索实体。不区分大小写的子串匹配。

参数：

• dataFilePath（必填）

• query（必填）— 搜索关键字

• entityTypes（可选）— 限定搜索类型（空 = 全部）

• cliPath（可选）

utmt-get-room-assets

获取一个房间内使用的所有资源：精灵（含尺寸及使用它们的对象）、对象（含位置和精灵）、代码条目（来自事件）以及图层汇总。

参数：

• dataFilePath（必填）

• roomName（必填）— 房间名称（如 scene_gameplay）

• cliPath（可选）

支持的数据文件格式

• data.win — Windows

• game.ios — iOS

• game.droid — Android

• game.unx — Linux/macOS

开发

git clone <repo>
cd utmt-mcp
pnpm install
pnpm run build

许可证

MIT

中文 · English

English

MCP server for reading and exporting GameMaker data files (.win, .ios, .droid, .unx) via UndertaleModCli.

Designed for LLM tool use — all output is clean JSON, entity lookup is by name.

Cross-platform — runs on Windows, macOS, and Linux. UndertaleModCli publishes builds for all three platforms.

Quick Start

npx utmt-mcp

Or install globally:

npm install -g utmt-mcp
utmt-mcp

Prerequisites

• Node.js 18+

• .NET runtime (required by UndertaleModCli)

• UndertaleModCli — either in PATH, or specify via env var / tool parameter

Installing UndertaleModCli

Download the build for your platform from GitHub Releases, extract, and either:

• Add the executable to your system PATH, or

• Set the UTMT_CLI_PATH environment variable to the full path of the executable

On Windows the CLI binary has a Windows executable suffix; on macOS and Linux it has no suffix. Everything else is identical.

Configuration

Environment Variables

MCP Client Configuration

In your MCP client (e.g. Claude Desktop, Cursor, Claude Code, etc.):

{
  "mcpServers": {
    "utmt": {
      "command": "npx",
      "args": ["-y", "utmt-mcp"],
      "env": {
        "UTMT_CLI_PATH": "/path/to/UndertaleModCli"
      }
    }
  }
}

Or with an explicit CLI path in each tool call (no env needed):

{
  "mcpServers": {
    "utmt": {
      "command": "npx",
      "args": ["-y", "utmt-mcp"]
    }
  }
}

Tools

utmt-info

Get overview of a GameMaker data file. Returns JSON with project name, GM version, isYYC flag, and resource counts.

Parameters:

• dataFilePath (required) — Path to the data file

• cliPath (optional) — Path to UndertaleModCli

utmt-list-entities

List entities of a given type. Returns JSON array with index, name, and brief properties.

Parameters:

• dataFilePath (required)

• entityType (required) — One of: sprites, sounds, scripts, code, rooms, gameobjects, fonts, backgrounds, paths, shaders, strings, timelines, embeddedtextures, embeddedaudio, extensions, sequences, particlesystems

• filter (optional) — Case-insensitive name filter

• offset (optional) — Pagination offset (default: 0)

• limit (optional) — Max results, 1-500 (default: 50)

• cliPath (optional)

utmt-get-entity

Get detailed info for a single entity. Returns JSON with all properties.

Parameters:

• dataFilePath (required)

• entityType (required) — One of: sprite, sound, script, code, room, gameobject, font, string, generalinfo

• name (required) — Entity name (or numeric index for string type; ignored for generalinfo)

• cliPath (optional)

utmt-decompile-code

Decompile a code entry back to GML source. Not available for YYC-compiled games.

Parameters:

• dataFilePath (required)

• codeName (required) — Code entry name (e.g. gml_Script_myFunction)

• cliPath (optional)

utmt-export-entity

Export a single entity to disk.

Parameters:

• dataFilePath (required)

• entityType (required) — One of: sprite, sound, code, embeddedtexture

• name (required) — Entity name (or numeric index for embeddedtexture)

• outputPath (required) — Output file or directory path

• cliPath (optional)

Export formats:

• sprite → PNG frames in output directory

• sound → .ogg or .wav file

• code → Decompiled .gml file

• embeddedtexture → PNG file

utmt-search

Search entities by name pattern across all types. Case-insensitive substring match.

Parameters:

• dataFilePath (required)

• query (required) — Search query

• entityTypes (optional) — Limit to specific types (empty = all)

• cliPath (optional)

utmt-get-room-assets

Get all assets used in a room: sprites (with dimensions and which objects use them), objects (with position and sprite), code entries (from events), and layer summary.

Parameters:

• dataFilePath (required)

• roomName (required) — Room name (e.g. scene_gameplay)

• cliPath (optional)

Supported Data File Formats

• data.win — Windows

• game.ios — iOS

• game.droid — Android

• game.unx — Linux/macOS

Development

git clone <repo>
cd utmt-mcp
pnpm install
pnpm run build

License

MIT