Nwn Mcp

NWN MCP Server

[](LICENSE)

An MCP (Model Context Protocol) server for Neverwinter Nights: Enhanced Edition module files (.mod). It wraps neverwinter.nim CLI tools to let AI assistants read, query, and modify NWN modules through structured tool calls.

Features

• Load and inspect .mod files — areas, creatures, items, dialogs, scripts, placeables, and more
• Create and edit areas, place objects, write dialogs, build quests
• Compile scripts, manage journals, link area transitions, and validate modules
• Bulk operations — rename tags, move or remove objects across areas, and orchestrate complex multi-step changes with natural language
• Search blueprints across the full resource stack (base game + HAKs + module)
• Spatial awareness — JSON payload of tile grids, walkable zones, and placed objects for AI reasoning
• Query and update NWN SQLite campaign databases
• HTML area reports — interactive visual maps of areas for human review

Bonus: A fully autonomous one-shot adventure creator. Give it a prompt, sit back, and get a playable module — areas painted, NPCs placed, quests written, loot balanced, all hands-free. Use /create-adventure and have fun. (Warning: spoiler-free by design — the DM gets surprised too.)

Designed for two workflows:

1. AI-assisted module design — You stay in creative control while an AI helps build, modify, and extend your module via natural language.
2. AI-driven adventure creation — A small, proof-of-concept tool that lets an LLM autonomously generate one-shot adventures for you and your friends — quests, dialogue, areas, and placed content from a high-level prompt. Spoiler-free by design, so the DM can be surprised too. Warning: Fully AI-generated content is best-effort, especially autonomous area painting. There may be dragons!

Prerequisites

• Node.js v18+
• neverwinter.nim tools — nwn_erf, nwn_gff, nwn_script_comp, nwn_twoda, nwn_resman_cat
• Neverwinter Nights: Enhanced Edition (for base game data)
• MCP-compatible AI client (Claude Code, Claude Desktop, VS Code, etc.)

Installation

1. Clone and build

git clone https://github.com/Txpple/nwn-mcp.git
cd nwn-mcp
npm install
npm run build

2. Download neverwinter.nim tools

Download the latest release for your platform from neverwinter.nim releases and extract the binaries to a folder you'll reference below.

3. Configure your MCP client

Add the server to your MCP client config. The config location depends on your client:

| Client | Config file | |--------|-------------| | Claude Code | .claude/settings.json or .mcp.json in your project | | Claude Desktop | claude_desktop_config.json | | VS Code | MCP settings in .vscode/mcp.json |

{
  "mcpServers": {
    "nwn-mcp": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/nwn-mcp",
      "env": {
        "NIM_FOLDER_NWTOOLS": "/path/to/neverwinter-nim-tools",
        "NWN_FOLDER_DATA": "/path/to/Neverwinter Nights",
        "NWN_FOLDER_USER": "/path/to/Documents/Neverwinter Nights"
      }
    }
  }
}

Windows paths example:

{
  "NIM_FOLDER_NWTOOLS": "C:/tools/neverwinter.nim/bin",
  "NWN_FOLDER_DATA": "C:/Program Files (x86)/Steam/steamapps/common/Neverwinter Nights",
  "NWN_FOLDER_USER": "C:/Users/you/Documents/Neverwinter Nights"
}

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | NIM_FOLDER_NWTOOLS | Yes | | Path to neverwinter.nim binaries | | NWN_FOLDER_DATA | Yes | | NWN game install directory (base game 2DA/TLK) | | NWN_FOLDER_USER | Yes | | NWN user documents directory (HAKs, overrides, modules) | | MCP_FOLDER_TEMP | No | %TEMP%/nwn-mcp | Temp directory for extracted modules | | MCP_FOLDER_USERREPORTS | No | | Directory for exported reports |

Usage

Once connected, call load_module with a module filename to begin:

load_module("mymodule.mod")

Then use any of the 110+ tools to inspect and modify the module. Ask your AI assistant things like:

• "Load my module and show me a summary"
• "Create a forest area with a river running through it"
• "Place a merchant NPC near the tavern door and give her a shop"
• "Write a quest where the player retrieves a stolen amulet from a goblin cave"
• "Add wolves and a bear encounter to the wilderness area"
• "Go through my custom classes and update descriptions"
• "Add some new power scripts to my custom feats"
• "Validate the module and check for broken references"

Changes are written back to the .mod file via repack_module.

Special Commands

• export_area_report / export_module_report — Generate interactive HTML maps of individual areas or the entire module for visual review in a browser.
• /create-adventure — Generate a complete one-shot adventure module from a creative prompt. Uses subagents to build areas, place NPCs, write quests, and populate the world autonomously.

Example /create-adventure prompts

/create-adventure I'd like to play an adventure in the wilderness where I fight off
animals and survive the elements. Give a somber tone. I'll be playing solo with a single level 2 character.

/create-adventure I'd like to play an adventure with city streets and thieves' guild
intrigue — sneaking, double-crosses, maybe a heist. Make it fun and cheeky. We'll be playing with a party of
3 level 5 characters.

/create-adventure I'd like to play an adventure where I'm an agent of a wizard society
sent to investigate the society's latest crisis. Classic tabletop style. Solo player,
level 4, lots of investigation and a climactic magical battle.

/create-adventure I'd like a classic dungeon crawl — an old crypt full of undead with
a powerful lich at the end. Make it old school classic gold box style. Party of 4 players around level 6.

/create-adventure Surprise me — you pick the setting, tone, and story. Solo player, level 3.

Just describe the kind of adventure you want to play and your party size and level — the skill takes it from there.

Available Tools

Areas

• create_area — create a new area with terrain tiles
• get_area_details — area properties, lighting, weather, music
• set_area_properties — modify lighting, fog, music, weather
• paint_tiles — set exact tile IDs on specific positions (direct placement)
• paint_group — place multi-tile groups (temples, lodges, etc.)
• adventure_apply_layout — apply a full layout atomically: zones + crossers + features via zone solver (adventure tool)
• get_tileset_details — tileset info with summary mode (~2KB) or full tile catalog (~60-100KB)

> Note: Terrain painting is best-effort — always open the module in the toolset to review painted areas and touch up as needed.

• visualize_area — spatial JSON payload for AI reasoning
• export_area_report / export_module_report — HTML visualizations for human review

Object Placement

• place_creature / place_placeable / place_door / place_waypoint — place objects in areas
• place_encounter / place_trigger / place_sound / place_store — encounters, triggers, sounds, stores
• move_object / remove_object / bulk_remove_objects — reposition or remove objects

Blueprints

• list_blueprints — search base game + HAK + module blueprints
• create_creature_blueprint / create_item_blueprint — create new blueprints
• create_encounter_blueprint / create_store_blueprint / create_trap_blueprint — encounters, stores, traps

Dialogs & Quests

• create_dialog / flatten_dialog / add_dialog_node — write and inspect conversations
• add_journal_quest / add_journal_entry — build quest journals
• verify_quest_completability — trace quests from dialog to journal end entry

Scripts

• write_script / compile_script / read_script_source — NWScript authoring
• search_scripts / list_script_references — find and trace script usage

Analysis

• validate_module — check for broken references across the module
• check_area_connectivity — verify all areas are reachable via transitions
• get_balance_report — creature difficulty and item values per area
• suggest_encounter — advisory tool for encounter composition by party level

Module Management

• load_module / repack_module — load and save modules
• get_module_info / get_module_summary — module metadata and overview
• undo_last_change / undo_history — revert recent changes

Adventure Creator

Tools specific to the /create-adventure pipeline for autonomous module building:

• adventure_generate_layout — procedural area layout generation with feature suggestions (dungeon, cave, dwelling, forest, rural, city, plains, desert, castle, tundra)
• adventure_apply_layout — atomically apply a generated layout (zones + crossers + features) via the zone solver
• adventure_list_features — enumerate solver-compatible feature groups for a tileset and style
• adventure_find_walkable — find guaranteed walkable coordinates in an area region
• adventure_create_transition — bidirectional portal transitions (single call places lights + waypoints in both areas)

Architecture

.mod file --> nwn_erf (extract) --> temp dir --> nwn_gff (parse GFF to JSON)
  --> in-memory ModuleIndex (tags, scripts, areas, dialogs, creatures, items)
    --> MCP tool handlers serve queries & modifications
      --> nwn_gff (serialize back) --> nwn_erf (repack) --> .mod file

One module is loaded at a time. The server builds a full resource manager stack on load — base game BIFs, module HAKs, user overrides, and module resources — giving tools access to the complete data hierarchy.

All tools carry MCP annotations (readOnlyHint, destructiveHint, idempotentHint) so clients can understand tool behavior. Adventure-creator-specific tools are separated into src/tools/adventure-tools.ts; all other tools are base tools for general module editing.

Scope

Targets non-persistent world modules — single-player and small co-op campaigns. Focused on instanced objects placed in areas (GIT contents). Blueprint modification, palette-level changes, and deep 2DA/ruleset authoring are out of scope. That being said, these are all possible with careful prompts.

Development

npm run dev          # Run with tsx (hot reload)
npm run build        # Compile TypeScript
npm run start        # Run compiled output
npm run test         # Run tests (vitest)
npm run lint         # Lint with Biome
npm run format       # Format with Biome

Troubleshooting

• neverwinter.nim tools not found — Verify NIM_FOLDER_NWTOOLS points to the directory containing the binaries, not a parent folder.

Support

• Issues: GitHub Issues

Acknowledgments

• Niv at neverwinter.nim for all the awesome stuff he's provided
• The NWN Discord and Zulip communities

License

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

Source & license

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

• Author: Txpple
• Source: Txpple/nwn-mcp
• License: MIT

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