WzImg MCP Server
MCP server enabling AI assistants to interact with MapleStory IMG files - 74 tools for reading, analyzing, modifying, and exporting game data
Ask AI about WzImg MCP Server
Powered by Claude ยท Grounded in docs
I know everything about WzImg MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
WzImg MCP Server Documentation
Version: 1.1.0
Overview
WzImg MCP Server is a Model Context Protocol (MCP) server that enables AI assistants (Claude, GPT, Gemini, etc.) 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 .img files with HaCreator, you will need the manifest.json!
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"
}
}
}
}
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"
}
}
}
}
Note: When using HTTP mode, the
WZIMGMCP_DATA_PATHenvironment variable should be set when starting the server, not in the client config. Theenvblock 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 Code โ 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, totalCount, and hasMore:
{ "totalCount": 150, "offset": 0, "limit": 50, "hasMore": true, "items": [...] }
Compact Mode
compact=true (default) returns minimal fields. Set compact=false for full property metadata.
Configuration
Limits are configurable in appsettings.json:
{
"HaMCP": {
"ResponseLimits": {
"MaxJsonResponseKB": 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: <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_json | Export to JSON. Params: path, maxDepth=5 (max 10), outputPath?. Error if >100KB without outputPath |
export_to_xml | Export to XML file. Params: path, 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.
