# Palworld Save MCP Server 🎮🛡️

[![MCP Standard](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-teal.svg)](LICENSE)
[![Official Web App](https://img.shields.io/badge/Web_GUI-CheckMySave.com-0d9488.svg)](https://www.checkmysave.com)

A Model Context Protocol (MCP) server that empowers AI assistants (Claude Desktop, Cursor, Windsurf, Zed) to diagnose, inspect, and troubleshoot **Palworld** game saves directly on your local machine or dedicated game server.

Official Web Companion: **[CheckMySave.com](https://www.checkmysave.com)** — 100% browser-local save health diagnostic tool.

---

## Features & Capabilities

- 🔍 **Container & Header Validation**: Validates `Level.sav` compression bounds (Oodle / Zlib / GVAS container) and detects truncation or corrupt headers.
- 👥 **Co-op Host Slot (0000...0001) Detection**: Prevents the infamous *"Host reset to Level 1"* disaster when migrating 4-player co-op saves to Linux/Windows dedicated servers.
- ⚙️ **WorldOption.sav Override Audit**: Flags conflicts where `WorldOption.sav` overrides `PalWorldSettings.ini` on dedicated servers, ignoring custom XP, capture rates, and death penalties.
- 🗄️ **Player Profile & World Parity**: Audits all `.sav` profiles inside `Players/` against world records.
- 💾 **Autosave Backup Check**: Scans for historical backup snapshots to ensure safe rollbacks.
- 🔒 **100% Local & Keyless**: Runs via standard stdio on your local computer. Zero remote API dependencies, zero telemetry, and zero credentials required.

---

## Tools

### 1. `inspect_palworld_save`
Runs a full 8-point diagnostic scan on a Palworld world directory.
- **Input:** `save_path` (string, path to folder containing `Level.sav` and `Players/`)
- **Output:** Detailed health scorecard (Pass / Warn / Fail) with actionable remediation steps.

### 2. `check_migration_readiness`
Evaluates whether a local co-op save is ready to migrate to a dedicated server without losing the host character.
- **Input:** `save_path` (string)
- **Output:** Status of the `00000000000000000000000000000001` host slot and step-by-step fix commands.

### 3. `check_server_override`
Checks whether `WorldOption.sav` is overriding `PalWorldSettings.ini`.
- **Input:** `save_path` (string)
- **Output:** Conflict resolution advice.

---

## Quickstart & Installation

### Option 1: Run via npx (No Install Required)
```bash
npx -y palworld-save-mcp
```

### Option 2: Claude Desktop Configuration

Add the following to your `claude_desktop_config.json`:

**MacOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "palworld-save": {
      "command": "npx",
      "args": ["-y", "palworld-save-mcp"]
    }
  }
}
```

### Option 3: Cursor / Windsurf Configuration

Add to your `.cursor/mcp.json` or Windsurf MCP config:

```json
{
  "mcpServers": {
    "palworld-save": {
      "command": "npx",
      "args": ["-y", "palworld-save-mcp"]
    }
  }
}
```

---

## Example AI Prompts

Once configured, you can ask your AI assistant:
- *"Claude, inspect my Palworld save at `C:\Users\Admin\AppData\Local\Pal\Saved\SaveGames\0\2E85FD38...` and tell me if it's healthy."*
- *"I want to move my 4-player co-op save to my Linux dedicated server. Check if my save is ready to migrate."*
- *"Why are my XP multiplier settings in PalWorldSettings.ini not applying on my server?"*

---

## Web GUI

For users who prefer a drag-and-drop web interface without installing Node.js or terminal tools, visit:  
👉 **[https://www.checkmysave.com](https://www.checkmysave.com)**

Runs 100% in your browser using client-side WebAssembly. No files are ever uploaded.

---

## License

MIT License — see [LICENSE](LICENSE) for details.