# WzImg MCP Server

> MCP for AI agents to interact with MapleStory .wz,.img,.pack files - 74 tools for reading, analyzing, modifying, and exporting game data

- **Type:** MCP server
- **Install:** `agentstack add mcp-lastbattle-wzimg-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lastbattle](https://agentstack.voostack.com/s/lastbattle)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [lastbattle](https://github.com/lastbattle)
- **Source:** https://github.com/lastbattle/WzImg-MCP-Server

## Install

```sh
agentstack add mcp-lastbattle-wzimg-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/lastbattle/Harepacker-resurrected), you will need the manifest.json!

  Extract .wz window
  

---

## Quick Start

### Installation

```bash
# 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.

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

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

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

```json
{
  "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](https://developers.openai.com/codex/mcp) for the full configuration reference.

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

```bash
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.

```bash
# 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`):

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

```toml
[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):**

```bash
# 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:
```md
- success: true
- data:
  - category: Map
  - image: 100000000.img
```

Typical failure output:
```md
- 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`:

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

```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):**
```md
- index: 0
- width: 100
- height: 120
- origin:
  - x: 50
  - y: 100
- delay: 120
```
When `metadataOnly=false`, each frame also includes:
```md
- 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](https://github.com/lastbattle)
- **Source:** [lastbattle/WzImg-MCP-Server](https://github.com/lastbattle/WzImg-MCP-Server)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-lastbattle-wzimg-mcp-server
- Seller: https://agentstack.voostack.com/s/lastbattle
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.