WzImg MCP Server

WzImg MCP Server Documentation

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: > ``bash > # 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 | Set HTTP server port (default: 13339) | | --data-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 | 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 |

---

Navigation

| 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: 

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: `

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lastbattle
• Source: lastbattle/WzImg-MCP-Server
• License: MIT

Install and usage instructions live in the source repository linked above.