WzImg MCP Server Documentation

July 9, 2026 · View on GitHub

Version: 1.1.0

Overview

WzImg MCP Server is a Model Context Protocol (MCP) server that enables AI agents to interact with MapleStory IMG files programmatically. It provides 74 tools across 10 categories for reading, analyzing, modifying, and exporting game data.

First export the .wz files into .img with HaCreator, you will need the manifest.json!

Extract .wz window

Quick Start

Installation

# Build the server
cd WzImg-MCP-Server
dotnet build WzImgMCP.csproj

Connection Methods

WzImg MCP Server supports two transport modes: stdio (standard input/output) and HTTP (Streamable HTTP with SSE).

MCP server name: wzimg

Method 1: Stdio (Default)

The stdio method runs the server as a subprocess. The client communicates via stdin/stdout.

# Run in stdio mode (default)
dotnet run --project WzImgMCP

Claude Desktop Configuration (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "wzimg": {
      "command": "dotnet",
      "args": ["run", "--project", "E:/path/to/WzImg-MCP-Server/WzImgMCP.csproj"],
      "env": {
        "WZIMGMCP_DATA_PATH": "D:\\Extract\\v83"
      }
    }
  }
}

Claude Code Configuration (.mcp.json in project root):

{
  "mcpServers": {
    "wzimg": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "E:/path/to/WzImg-MCP-Server/WzImgMCP.csproj"],
      "env": {
        "WZIMGMCP_DATA_PATH": "D:\\Extract\\v83"
      }
    }
  }
}

Codex Configuration (~/.codex/config.toml or project-scoped .codex/config.toml):

Codex supports MCP servers in the CLI and IDE extension. Both clients share config.toml, so you only need to configure the server once. See the Codex MCP documentation for the full configuration reference.

[mcp_servers.wzimg]
command = "dotnet"
args = ["run", "--project", "E:/path/to/WzImg-MCP-Server/WzImgMCP.csproj"]

[mcp_servers.wzimg.env]
WZIMGMCP_DATA_PATH = "D:\\Extract\\v83"

You can also add the stdio server from the Codex CLI:

codex mcp add wzimg --env WZIMGMCP_DATA_PATH=D:/Extract/v83 -- dotnet run --project E:/path/to/WzImg-MCP-Server/WzImgMCP.csproj

In the Codex TUI, run /mcp to confirm that wzimg is available.

Method 2: HTTP (Streamable HTTP)

The HTTP method runs the server as a standalone web service. Clients connect via HTTP requests with Server-Sent Events (SSE) for streaming responses.

# Run in HTTP mode
dotnet run --project WzImgMCP -- --http

# Or specify a custom port
dotnet run --project WzImgMCP -- --http --port 8080

Claude Code Configuration (.mcp.json):

{
  "mcpServers": {
    "wzimg": {
      "type": "http",
      "url": "http://127.0.0.1:13339/mcp",
      "env": {
        "WZIMGMCP_DATA_PATH": "D:\\Extract\\v83"
      }
    }
  }
}

Codex Configuration (~/.codex/config.toml or project-scoped .codex/config.toml):

Start the WzImg MCP Server separately, then point Codex at the HTTP endpoint:

[mcp_servers.wzimg]
url = "http://127.0.0.1:13339/mcp"

Note: When using HTTP mode, the WZIMGMCP_DATA_PATH environment variable should be set when starting the server, not in the client config. The env block above is shown for reference but is only applied by the client when spawning the server (stdio mode). For HTTP mode, set it before running the server:
# Windows
set WZIMGMCP_DATA_PATH=D:\Extract\v83
dotnet run --project WzImgMCP -- --http

# Linux/macOS
WZIMGMCP_DATA_PATH=/path/to/data dotnet run --project WzImgMCP -- --http

Using with curl (testing):

# Initialize connection (returns session ID)
curl -X POST http://127.0.0.1:13339/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{}},"id":1}'

# Call a tool
curl -X POST http://127.0.0.1:13339/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_categories","arguments":{}},"id":2}'

Environment Variables

Variable	Description
`WZIMGMCP_DATA_PATH`	Path to IMG filesystem extracted by HaCreator (must contain `manifest.json`)
`WZIMGMCP_PORT`	Server port for HTTP mode (default: 13339)
`WZIMGMCP_TRANSPORT`	Transport mode: `stdio` (default) or `http`

Command Line Arguments

Argument	Description
`--http`	Run in HTTP mode instead of stdio
`--port <port>`	Set HTTP server port (default: 13339)
`--data-path <path>`	Set data source path

Comparison: Stdio vs HTTP

Feature	Stdio	HTTP
Startup	Launched per-session by client	Runs as persistent service
Performance	Low latency (direct IPC)	Slight overhead (TCP/HTTP)
Multiple clients	One client per process	Multiple concurrent clients
Debugging	Harder (subprocess)	Easier (standalone process)
Deployment	Embedded	Can run on remote server
Best for	Claude Desktop, local dev	CI/CD, remote access, shared servers

Expected Directory Structure:

D:\Extract\v83\
├── manifest.json          # Version metadata (required)
├── Character/
│   ├── 00002000.img
│   ├── 00012000.img
│   └── ...
├── Map/
│   ├── Map0/
│   │   ├── 000010000.img
│   │   └── ...
│   └── ...
├── Mob/
├── Npc/
├── Sound/
└── ...

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                              AI Clients                                 │
├─────────────────┬─────────────────┬─────────────────────────────────────┤
│  Claude Desktop │  Claude/Codex   │        Other MCP Clients            │
│   (subprocess)  │  (CLI/remote)   │      (custom applications)          │
└────────┬────────┴────────┬────────┴─────────────────┬───────────────────┘
         │                 │                          │
         │ stdio           │ stdio or HTTP            │ HTTP
         │                 │                          │
         ▼                 ▼                          ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           WzImg MCP Server                              │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │                      Transport Layer                               │ │
│  │  ┌─────────────────────┐      ┌──────────────────────────────────┐ │ │
│  │  │   Stdio Transport   │      │       HTTP Transport             │ │ │
│  │  │   (stdin/stdout)    │      │   (Streamable HTTP + SSE)        │ │ │
│  │  │                     │      │   Port: 13339 (default)          │ │ │
│  │  └──────────┬──────────┘      └────────────────┬─────────────────┘ │ │
│  └─────────────┼──────────────────────────────────┼───────────────────┘ │
│                │                                  │                     │
│                └────────────────┬─────────────────┘                     │
│                                 ▼                                       │
│                    ┌─────────────────────────┐                          │
│                    │   MCP Protocol Handler  │                          │
│                    │   (JSON-RPC 2.0)        │                          │
│                    └────────────┬────────────┘                          │
│                                 ▼                                       │
│                    ┌─────────────────────────┐                          │
│                    │      Tool Classes       │                          │
│                    │   (74 tools, ToolBase)  │                          │
│                    └────────────┬────────────┘                          │
│                                 ▼                                       │
│                    ┌─────────────────────────┐                          │
│                    │   WzSessionManager      │                          │
│                    │   (cache, state)        │                          │
│                    └────────────┬────────────┘                          │
│                                 ▼                                       │
│                    ┌─────────────────────────┐                          │
│                    │       MapleLib          │                          │
│                    │    (WZ/IMG I/O)         │                          │
│                    └─────────────────────────┘                          │
└─────────────────────────────────────────────────────────────────────────┘

Core Components

Component	Description
`ToolBase`	Base class providing session validation and error handling
`Result<T>`	Internal wrapper used by tools before Markdown rendering
`WzSessionManager`	Manages loaded data sources and image cache
`WzDataConverter`	Converts WZ properties to serializable formats

Response Format

All MCP tools now return Markdown text (plain string output) instead of JSON objects.

Typical success output:

- success: true
- data:
  - category: Map
  - image: 100000000.img

Typical failure output:

- success: false
- error: No data source initialized

Response Size Optimization

Tools support pagination and compact modes to minimize response size. These are enabled by default.

Pagination

Paginated responses include offset, limit, total_count, and has_more:

- total_count: 150
- offset: 0
- limit: 50
- has_more: true
- items:
  -
    - name: example

Compact Mode

compact=true (default) returns minimal fields. Set compact=false for full property metadata.

Configuration

Limits are configurable in appsettings.json:

{
  "HaMCP": {
    "ResponseLimits": {
      "MaxMarkdownResponseKB": 512,
      "MaxBase64ImageKB": 256,
      "DefaultSearchResults": 20,
      "DefaultPropertyPageSize": 50
    }
  }
}

Tool Reference

All tools accept category and image parameters unless noted. Paths use / separator (e.g., info/bgm).

File Operations

Tool	Description
`init_data_source`	Initialize data source from directory containing `manifest.json`. Params: `basePath`
`scan_img_directories`	Scan directory for available data sources. Params: `path`, `recursive=true`
`get_data_source_info`	Get current data source metadata and cache stats
`list_categories`	List available categories (Map, Mob, Npc, etc.)
`list_images_in_category`	List .img files. Params: `category`, `subdirectory?`
`get_cache_stats`	Get cache hit ratio and memory usage
`clear_cache`	Clear loaded image cache

Tool	Description
`get_subdirectories`	List subdirectories in a category
`list_properties`	List child properties. Params: `path?`, `compact=true`, `offset=0`, `limit=50` (max 500)
`get_tree_structure`	Get property tree. Params: `path?`, `depth=2` (max 5), `maxChildrenPerNode=50` (max 200). Hard limit: 1000 nodes
`search_by_name`	Search by name pattern (`*` wildcards). Params: `pattern`, `category?`, `image?`, `compact=true`, `maxResults=20` (max 200)
`search_by_value`	Search by value. Params: `value`, `type?`, `category?`, `image?`, `compact=true`, `maxResults=20` (max 200)
`get_property_path`	Get full path of a property

Property Access

Tool	Description
`get_property`	Get property with full metadata
`get_property_value`	Get just the value
`get_string`	Get string value. Params: `path`, `defaultValue?`
`get_int`	Get integer value. Params: `path`, `defaultValue?`
`get_float`	Get float value. Params: `path`, `defaultValue?`
`get_vector`	Get vector (X, Y)
`resolve_uol`	Resolve UOL link to target property
`get_children`	Get child properties. Params: `path?`, `compact=true`, `offset=0`, `limit=50` (max 500)
`get_property_count`	Count child properties
`iterate_properties`	Iterate with full metadata. Params: `path?`, `offset=0`, `limit=50`
`get_properties_batch`	Batch get. Params: `requests[]` with `{category, image, path}`

Property Types: Null, Short, Int, Long, Float, Double, String, SubProperty, Canvas, Vector, Sound, UOL, Lua, Convex

Canvas Operations

Tool	Description
`get_canvas_bitmap`	Get image as base64 PNG
`get_canvas_info`	Get metadata (dimensions, format, origin, delay) without image data
`get_canvas_origin`	Get draw offset point (X, Y)
`get_canvas_head`	Get head position for character rendering
`get_canvas_bounds`	Get lt/rb bounds
`get_canvas_delay`	Get frame delay in milliseconds
`get_animation_frames`	Get frames. Params: `path`, `metadataOnly=true`, `offset=0`, `limit=5` (max 50). Returns `frameCount`, `totalDuration`, `hasMore`
`list_canvas_in_image`	List all canvases. Params: `maxDepth=10`
`resolve_canvas_link`	Resolve `_inlink`/`_outlink` references

Frame structure (Markdown response):

- index: 0
- width: 100
- height: 120
- origin:
  - x: 50
  - y: 100
- delay: 120

When metadataOnly=false, each frame also includes:

- base64_png: <base64 data>

When metadataOnly=true, base64_png is omitted.

Audio Operations

Tool	Description
`get_sound_info`	Get metadata (duration, format, frequency)
`get_sound_data`	Get audio as base64
`list_sounds_in_image`	List all sounds. Params: `maxDepth=10`
`resolve_sound_link`	Resolve UOL to sound

Export Operations

Tool	Description
`export_to_md`	Export property tree to Markdown and writes `.md` files. Params: `path`, `maxDepth=5` (max 10), `outputPath?`. Error if >100KB without `outputPath`
`export_png`	Export canvas to PNG. Params: `path`, `outputPath`
`export_mp3`	Export sound to MP3. Params: `path`, `outputPath`
`export_all_images`	Batch export canvases. Params: `outputPath`
`export_all_sounds`	Batch export sounds. Params: `outputPath`

Analysis

Tool	Description
`get_statistics`	Get data source statistics
`get_category_summary`	Summarize category (image count, size)
`find_broken_uols`	Find broken UOL references
`compare_properties`	Compare two properties. Params: `source{category,image,path}`, `target{...}`
`get_version_info`	Get server version
`validate_image`	Validate image structure

Modification

Tool	Description
`set_string`	Set string value
`set_int`	Set integer value
`set_float`	Set float value
`set_vector`	Set vector. Params: `path`, `x`, `y`
`add_property`	Add property. Params: `path`, `name`, `type`, `value`
`delete_property`	Delete property
`rename_property`	Rename. Params: `path`, `newName`
`copy_property`	Deep copy. Params: `source{...}`, `target{...}`
`set_canvas_bitmap`	Replace image. Params: `path`, `base64Png`
`set_canvas_origin`	Set origin. Params: `path`, `x`, `y`
`import_png`	Import PNG. Params: `path`, `pngPath`
`import_sound`	Import audio. Params: `path`, `soundPath`
`save_image`	Save changes to disk
`discard_changes`	Revert unsaved changes

Batch Operations

Tool	Description
`extract_to_img`	Extract WZ to IMG. Params: `wzPath`, `outputPath`
`pack_to_wz`	Pack IMG to WZ. Params: `imgPath`, `outputPath`
`batch_export_images`	Export category images. Params: `category`, `outputPath`
`batch_search`	Search across categories. Params: `pattern`, `categories[]`, `maxResults`

Lifecycle

Tool	Description
`parse_image`	Parse image into memory
`unparse_image`	Free image memory
`is_image_parsed`	Check if parsed
`get_parsed_images`	List parsed images
`preload_category`	Preload all images in category
`unload_category`	Unload all images in category

Code Architecture

ToolBase Pattern

All tool classes extend ToolBase for consistent error handling:

public class MyTools : ToolBase
{
    public MyTools(WzSessionManager session) : base(session) { }

    [McpServerTool(Name = "my_tool")]
    public string MyTool(string param)
    {
        return Execute(() =>
        {
            // Business logic here
            return new MyData { ... };
        });
    }
}

Execute Helpers

Method	Description
`Execute<T>()`	Validates session, catches exceptions
`ExecuteRaw<T>()`	No session check (for init operations)
`GetImage()`	Get parsed WzImage
`GetProperty()`	Get property by path
`GetRequiredProperty<T>()`	Get typed property (throws if not found)

Result Types

// Internal result wrapper used before Markdown conversion
public class Result<T>
{
    public bool Success { get; init; }
    public string? Error { get; init; }
    public T? Data { get; init; }
}

// Common data types
public record Point2D(int X, int Y);
public record Size2D(int Width, int Height);

Project Structure

WzImgMCP/
├── Program.cs                 # Entry point
├── Core/
│   ├── Result.cs              # Generic result types
│   └── ToolBase.cs            # Base class for tools
├── Server/
│   └── WzSessionManager.cs    # Session management
├── Tools/
│   ├── FileTools.cs           # 7 tools
│   ├── NavigationTools.cs     # 6 tools
│   ├── PropertyTools.cs       # 11 tools
│   ├── ImageTools.cs          # 9 tools
│   ├── AudioTools.cs          # 4 tools
│   ├── ExportTools.cs         # 6 tools
│   ├── AnalysisTools.cs       # 6 tools
│   ├── ModifyTools.cs         # 14 tools
│   ├── BatchTools.cs          # 4 tools
│   └── LifecycleTools.cs      # 6 tools
└── Utils/
    └── WzDataConverter.cs     # Type conversion utilities

Testing

# Run unit tests
dotnet test WzImgMCP.Tests

# Test with MCP Inspector
npx @modelcontextprotocol/inspector dotnet run --project WzImgMCP

Dependencies

<PackageReference Include="ModelContextProtocol" Version="0.1.0-preview" />
<ProjectReference Include="..\MapleLib\MapleLib.csproj" />

License

MIT

Copyright (c) 2026, LastBattle https://github.com/lastbattle
 
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.