Morrowind Model Context Protocol Server (Morrowind MCP) connects Morrowind to external LLM AIs (such as ChatGPT, Claude, Copilot, or Gemini) using MCP standard.
This mod allows the AI to learn about the world of Morrowind and interact with it.
This mod contains source code generated or assisted by AI. and all code has been manually reviewed, refactored and verified by a senior software engineer.
- Install Morrowind full expansion, MGE XE, MWSE, MCP, and optionally MO2 and MGE XE UF.
- Install this mod into Morrowind's
Data Filesfolder or using MO2. - Setup
mcp.jsonor client specific file for an AI agent configuration. See MCP Configuration for details. - Start Morrowind with MWSE and this mod.
- Connect to this MCP server using
mcp.json - Use or Chat an AI agent tools, prompts and resources to interact with Morrowind world.
- Morrowind full expansion
- Morrowind Graphics Extender XE (MGE XE): Due to contains MWSE. And it extends Morrowind's graphics.
- Morrowind Script Extender (MWSE): Run MWSE-Update.exe for getting the latest version. It is required for this MCP server mod.
- Morrowind Script Extender Community Patch (MCP) or MCP Beta : Run Morrowind Code Patch.exe. it fixes many bugs in Morrowind.
- (Optional) Mod Organizer 2 (MO2): for managing mods. Also useful for development and testing.
- (Optional) MGE XE UF: It is unofficial update for MGE XE.
| Client | Project config file | User config file | Sample | Notes |
|---|---|---|---|---|
| VSCode | .vscode/mcp.json | %APPDATA%/Code/User/mcp.json | sample | MCP configuration reference |
| Claude Desktop | .mcp.json | %APPDATA%/Claude/claude_desktop_config.json | sample | Connect to local MCP servers |
| Claude Code | .mcp.json | %USERPROFILE%/.claude.json | sample | Connect to MCP servers |
| Cursor | .cursor/mcp.json | %USERPROFILE%/.cursor/mcp.json | sample | Model Context Protocol (MCP) |
| ChatGPT Codex | .config.toml | %USERPROFILE%/.codex/config.toml | sample | Advanced Configuration |
| Antigravity | .agents/mcp_config.json | %USERPROFILE%/.gemini/config/mcp_config.json | sample | Model Context Protocol (MCP) |
{
"servers": {
"morrowind-mcp": {
"type": "http",
"url": "http://localhost:33427"
}
}
}Requires Node.js
{
"mcpServers": {
"morrowind-mcp": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:33427"
]
}
}
}{
"mcpServers": {
"morrowind-mcp": {
"type": "streamable-http",
"url": "http://localhost:33427"
}
}
}[mcp_servers.morrowind-mcp]
enabled = true
url = "http://localhost:33427"{
"mcpServers": {
"morrowind-mcp": {
"serverUrl": "http://localhost:33427"
}
}
}This MCP server does not modify the game or generate and execute new code; it only performs actions that are possible within the game itself.
Tools and prompts remain listed while their runtime prerequisites are unavailable. The tool catalog is fixed when the server starts; tools excluded by startup configuration are not registered. Call mw-capabilities-fetch to read each published tool's general conditions; this is guidance rather than a current-state guarantee. Each tools/call and prompts/get validates the normalized arguments and current game state immediately before execution. Runtime tool failures return isError: true with a machine-readable reason and recovery guidance.
- Prompts and Tools name must be in
kebab-case. - (mcp prefix)-(object)-(action)
- mcp prefix:
mw(Morrowind) - Example:
mw-menu-fetch,mw-screenshot-save
- mcp prefix:
- Arguments name must be in
snake_case.
This configuration system is designed to handle differences between user environments, such as Morrowind install locations, Mod Organizer 2 setup, and profile-specific paths. By layering default, local, and env values, the project can run consistently across personal setups, test machines, and CI.
Precedence: env > local > default.
- Environment variables can be used to override values in
mwmcp.local.jsonfor CI or other purposes. For example,MWMCP_SERVER_ADDRESScan override theserver.addressvalue. - Local development overrides can be placed in mwmcp.local.json.
- The default values live in mwmcp.defaults.json.
Environment variables:
| Variable | Overrides | Meaning |
|---|---|---|
MWMCP_SERVER_ADDRESS |
server.address |
This server host name or IP address |
MWMCP_SERVER_PORT |
server.port |
This server TCP port |
MWMCP_MO2_EXE_FILE |
paths.mo2ExeFile |
Mod Organizer 2 executable file path |
MWMCP_MO2_APPLICATION |
paths.mo2Application |
Mod Organizer 2 application name to launch |
MWMCP_MO2_PROFILE |
paths.mo2Profile |
Mod Organizer 2 profile name |
MWMCP_MORROWIND_INSTALL_DIR |
paths.morrowindInstallDir |
Morrowind install directory path |
MWMCP_DATAFILES_OVERWRITE_DIR |
paths.datafilesOverwriteDir |
Data Files overwrite directory path; Lua runtime mod data writes resolve to <datafilesOverwriteDir>/MWSE/mods/morrowind-mcp; MWSE config resolves to <datafilesOverwriteDir>/MWSE/config |
Server-generated Lua output data can be inspected under <paths.datafilesOverwriteDir>/MWSE/mods/morrowind-mcp. The shared config helper exposes this physical path as Paths.modDataDir; script-created sentinel files are not considered server output data.
- tests/unit_test.ps1: Run Lua unit tests for MWSE mod modules. Pass test file names to run only those files.
- tests/server_test.ps1: Start Morrowind/MWSE server, run integration tests, and stop the server
- By default, after connectivity is confirmed, it attempts to bring Morrowind to the foreground. This is required for tests that use keyboard key or mouse button input, because those inputs are not sent while Morrowind is in the background.
- For tests that do not require input sending, run with
-NoForegroundto skip foreground activation and the capture click.
- tests/sse_test.ps1: Start Morrowind/MWSE server, open an SSE stream, verify a server-to-client notification
- tests/completion_test.ps1: Start Morrowind/MWSE server and verify deterministic resource-template completion through raw JSON-RPC
- tests/start_server_mo2.ps1: Launch Mod Organizer 2 to start Morrowind with MWSE and the MCP server
- tests/stop_server.ps1: Stop the currently running Morrowind
- tests/mwmcp_config.ps1: Resolve configuration precedence (env > local > default) and provide paths for tests
Saved test artifacts and summary_<timestamp>.json are described in docs/test-run-summaries.md.
Run tests/start_inspector.ps1 to launch the MCP Inspector UI:
.\tests\start_inspector.ps1This automatically resolves the server configuration and opens the Inspector at the configured connection URL.
Run a main-menu or saved-game Inspector suite with tests/server_integration_test.ps1:
.\tests\server_integration_test.ps1 --list-suites
.\tests\server_integration_test.ps1 --suite main-menuSet MWMCP_PYTHON_EXE when Python 3.14 is not installed at the default uv-managed location.
Run tests/mcp_discover.ps1 to create an independent Streamable HTTP session and write the current initialize, tools/list, resources/list, resources/templates/list, and prompts/list results. URI templates are stored in resource_templates, separately from the concrete resources list:
.\tests\mcp_discover.ps1 -OutputPath .\tests\logs\mcp_discovery\initial.jsonUse -WatchSeconds to keep its session-scoped SSE connection open. On a *_list_changed notification it automatically refreshes the corresponding list and appends the evidence to the JSON record:
.\tests\mcp_discover.ps1 -WatchSeconds 60 -OutputPath .\tests\logs\mcp_discovery\watch.jsonThe script connects to an already running server and deletes its independent session when it exits; it does not launch or stop Morrowind.
Session cleanup failure also produces a nonzero exit code, even if the discovery record has already been written. If discovery and cleanup both fail, the primary error is reported first, followed by the cleanup error.
tests/mcp_read.ps1 is an optional HttpClient helper for reading one resource from an already running server:
.\tests\mcp_read.ps1 -Uri "morrowind://memory/index.json"It resolves the endpoint through the shared configuration, initializes its own session, reads the requested URI, and deletes the session on exit. It does not accept or reuse a session ID. Inspector CLI remains an alternative; this helper requires PowerShell/.NET but not Node.js or Inspector.
On success, stdout contains the JSON resources/read result (contents), without the JSON-RPC envelope. Failures are reported on stderr with a nonzero exit code. -Uri must be non-empty. -TimeoutSeconds defaults to 30 (range 1-300) and bounds each HTTP request, including session cleanup; it is not a total-run deadline. This helper supports this server's JSON POST responses, not SSE-formatted POST responses, and opens no notification stream.
If session cleanup fails or times out, the read helper exits nonzero and does not output the result, even when the read itself succeeded.
Run the focused, server-independent transport fixtures with .\tests\mcp_resource_operations_fixture_test.ps1 in PowerShell 7 or later (pwsh).
| HTTP Method | Behavior | Notes |
|---|---|---|
POST |
Client-to-server JSON-RPC requests and notifications | Uses JSON payloads |
GET |
Opens the session-scoped SSE stream for server-to-client notifications | Requires Accept: text/event-stream |
DELETE |
Ends the Streamable HTTP session | Uses MCP-Session-Id |
OPTIONS |
Handles CORS preflight requests | Allows POST, GET, DELETE, and OPTIONS |
The server returns MCP-Session-Id on initialize; clients must send it on subsequent POST and GET requests for that session.
If the same session opens another SSE GET, the server replaces the previous SSE stream with the newest one.
| MCP Method | Supported |
|---|---|
completion/complete |
Yes |
elicitation/create |
No (undecided) |
initialize |
Yes |
logging/setLevel |
Yes |
notifications/cancelled |
Yes |
notifications/initialized |
Yes |
notifications/tasks/status |
No (undecided) |
notifications/message |
Yes |
notifications/progress |
Yes (but it isn't used) |
notifications/prompts/list_changed |
Yes (but it won't change) |
notifications/resources/list_changed |
Yes |
notifications/resources/updated |
Yes |
notifications/roots/list_changed |
No (undecided) |
notifications/tools/list_changed |
Yes (but it won't change) |
notifications/elicitation/complete |
No (undecided) |
ping |
Yes |
tasks/get |
No (undecided) |
tasks/result |
No (undecided) |
tasks/list |
No (undecided) |
tasks/cancel |
No (undecided) |
prompts/get |
Yes |
prompts/list |
Yes |
resources/list |
Yes |
resources/read |
Yes |
resources/subscribe |
Yes |
resources/templates/list |
Yes |
resources/unsubscribe |
Yes |
roots/list |
No (undecided) |
sampling/createMessage |
No (undecided) |
tools/call |
Yes |
tools/list |
Yes |
Pagination is not supported yet. All lists are returned in a single response.
- base64.lua from lbase64: MIT License or Public Domain
- During Bink movie playback, MWSE execution can pause completely. While a movie is playing, this server may stop responding to MCP requests until the movie ends.
- Impact:
tools/callrequests that trigger movie playback (for example, starting a new game from the main menu) can appear to hang, and a response may not be returned until playback finishes. - Current workaround: replace movie files under
Data Files/Videowith dummy files to prevent movie playback. Keep backups of original files and restore them when needed.
- OpenMW is not supported yet. I'd like to do it, but it's simply because I don't know much about modding with OpenMW.
Disclaimer Version: 1
This software is designed to operate in conjunction with Large Language Models (LLMs) and other Artificial Intelligence technologies ("AI"). Due to the inherent nature of AI and automation, it may produce inaccurate outputs, unexpected commands, or malfunctions (including, but not limited to, hallucinations). The developer shall not be liable for any direct, indirect, incidental, or consequential damages, data loss, system failures, or other disadvantages arising from operations performed under AI direction or from reliance on AI-generated output (such as data modification, deletion, external communication, or system configuration changes). Users are solely responsible for reviewing, managing, and monitoring connected AI services, prompts, instructions, and execution results.
This software runs locally, but it is intended to be used with external AI clients and/or LLM services through the Model Context Protocol (MCP). When so used, data exposed through the MCP interface, including file contents, logs, and system information, may be transmitted to and processed by third-party services selected by the user. By accepting the in-game disclaimer and enabling the MCP server, you acknowledge and agree that such data may be transmitted to and processed by those services. The handling, confidentiality, and privacy of transmitted data are governed by the terms, privacy policies, and security practices of the respective providers, as well as by the configuration choices made by the user. If you do not accept this disclaimer, the MCP server will not start. Do not use this software with confidential, sensitive, or personally identifiable information unless you fully understand and accept those risks.
This 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.