No Man's Sky Direct Link — MCP server for No Man's Sky

◆ TL;DR

• What it is: an MCP server (nms-direct-link) that decodes save.hg, de-obfuscates it with the community key mapping, and exposes 37 tools (36 read-only) to Claude Desktop, Claude Code, or any MCP client, and to any assistant that can run a command (Grok, ChatGPT desktop, scripts) through a built-in command-line bridge.

• What it never does: write to your save, touch the game process, read memory, intercept network traffic, or send your data anywhere. The only network call is an optional public community-mission lookup. The only files it writes are a small session-history log and your scanned-shops database, both in your user cache folder.

• Install: pipx install git+https://github.com/Zeekeey-jpeg/No-Mans-Sky-Direct-Link then add one JSON block to your MCP client. Saves are found automatically (Steam, GOG).

• Check it works: nms-direct-link --self-test

• No MCP? No problem: nms-direct-link --call station_brief prints the same answer an MCP client gets.

save: C:\Users\you\AppData\Roaming\HelloGames\NMS\st_7656…\save.hg (12 min ago)
version 4745 · Win|Final · mapping libMBIN 7.10.0.1 · unknown keys 0
mode Normal · 41.2 h · units 12,480,300 · nanites 1,930 · quicksilver 450
location Euclid 0863:007C:060B:01AB planet 1 (portal 11AB7E60D865)
inventories 19 · ships 3 · multitools 2 · bases 4 · teleporters 15
discoveries 512 · pending upload 143 {'Mineral': 61, 'Flora': 39, 'Animal': 28, 'Planet': 9, 'SolarSystem': 6}
frigates 7 · expeditions 1 · settlements 1 · missions in progress 24
SELF-TEST OK

Related MCP server: palworld-save-mcp

◆ Shop Scanner: dock and ask "what's here?"

The game never saves what a merchant is selling. Direct Link reads it the way you do: off the screen.

1. Dock and open a shop. Technology merchant, starship outfitter, trade terminal, scrap dealer, mission board, anything.

2. Ask "what's in this shop?" Your assistant grabs a screenshot of the game window, reads every item, class and price, and tells you what's worth buying with the nanites and units you actually have.

3. It remembers. Every shop you scan is saved against that system. Later, from anywhere: "Which station had an S-class hyperdrive module under 600 nanites?" · "Quick view: what did the shops here sell?"

Don't want to alt-tab? Press Steam's F12 at each shop while you play, then ask "read my screenshots" once. Every shop gets logged in one go.

From the cockpit. Dock, stay in your ship and ask "what's at this station for me?". The station brief checks your wallet, every shop you've scanned here before, the upgrades you're missing or running low-class on, and goods you've already crashed the price of here. Then it tells you which merchant to open first. The game doesn't save unscanned stock, so nothing can read a merchant you haven't opened; the brief makes sure you only open the one worth it.

Run the game borderless or windowed for window capture (exclusive fullscreen can capture black). Only the game window is captured: if it isn't found, nothing is taken unless you explicitly ask for the whole screen. Re-scanning a merchant replaces its earlier list. Capture never touches the game process; it's the same as a screenshot tool or OBS. Images go only to the assistant you are talking to.

◆ Works with any assistant: command-line bridge

Not every assistant speaks MCP. If yours can run a command on your PC (Grok desktop, ChatGPT desktop, a script, a Stream Deck button), point it at the program and it gets the exact same answers:

nms-direct-link --list-tools                                   # every tool and what it does
nms-direct-link --call station_brief                           # "what's at this station for me?"
nms-direct-link --call plan_nanites --args "{\"target\": 3000}"   # any tool, any parameters (JSON)
nms-direct-link --call get_player_state --args "{\"response_format\": \"json\"}"

PowerShell wants single quotes around the JSON: nms-direct-link --call plan_nanites --args '{"target": 3000}'.

The nms_ prefix is optional. Exit codes: 0 success, 1 the tool reported an error, 2 bad tool name or parameters. Where the installer put it: pipx → %USERPROFILE%\.local\bin\nms-direct-link.exe; a virtual environment → <venv>\Scripts\nms-direct-link.exe.

◆ Before & after

Everything the current No Man's Sky MCP tooling can do, Direct Link does too. Then it reads what's on your screen in any shop, and the rest of your save: money, tech, inventories, fleet, corvettes, companions, missions, reputation, trade, records, timers and session-to-session progress.

◆ Features

You and your stuff

Exploring and travelling

Progress, money and time

Shop Scanner

Help and housekeeping

Every tool takes response_format: "markdown" | "json" and an optional slot. Resources: nms://player/state, nms://galaxy/stats, nms://bases.

Freshness. The game writes the save at save points, when you exit your ship and on a periodic autosave. The server reloads automatically when the file changes, so answers lag live play by seconds to a few minutes.

◆ Install

Requires Python 3.11+ and No Man's Sky on PC (Steam or GOG; Xbox/Game Pass saves are on the roadmap).

1. Install the server

# recommended: isolated install
pipx install git+https://github.com/Zeekeey-jpeg/No-Mans-Sky-Direct-Link

# or with uv
uv tool install git+https://github.com/Zeekeey-jpeg/No-Mans-Sky-Direct-Link

# or plain pip
pip install git+https://github.com/Zeekeey-jpeg/No-Mans-Sky-Direct-Link

2. Check it sees your save

nms-direct-link --list-saves
nms-direct-link --self-test

If nothing is found, point it at your account folder (the one containing save.hg):

3. Add it to your MCP client

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "nms-direct-link": {
      "command": "nms-direct-link"
    }
  }
}

Claude Code:

claude mcp add nms-direct-link -- nms-direct-link

Any other MCP client: run nms-direct-link over stdio, or nms-direct-link --transport streamable-http --port 5099 for an HTTP endpoint on 127.0.0.1.

4. After a game update

nms-direct-link --update-mapping

This downloads the newest key mapping published with MBINCompiler so new save fields decode. If the self-test reports unmapped keys after a patch, run this first.

◆ Example conversation

You: How am I doing and what should I do about nanites?

Assistant: (calls nms_get_player_state, nms_plan_nanites) You're in Euclid on planet 1 of system 427, Normal mode, with 12.5M units and 1,930 nanites. You have 143 discoveries waiting to be uploaded: that's free nanites before you fly anywhere. After that, the fastest method you can run right now is a Runaway Mould farm; ship scrapping is blocked until you have a bigger units bankroll…

You: Is anything on my ship broken, and where's my Chromatic Metal?

Assistant: (calls nms_audit_tech, nms_find_item) Your hauler has an S-class and an X-class hyperdrive module installed, nothing damaged. 2,500 Chromatic Metal is in your freighter's main inventory…

◆ Privacy, safety and the rules

• Read-only, always. The server opens save*.hg for reading. There is no code path that writes to the save, the game folder, or the game process.

• Offline by default. All save tools work without internet. nms_get_community_mission calls a public third-party API and sends nothing about you. --update-mapping downloads one JSON file from GitHub.

• No memory reading, no injection, no packet capture. Those are grey-to-prohibited under the No Man's Sky EULA and are deliberately out of scope.

• Your data stays yours. Logs go to stderr only. Two files are written, both in your user cache folder. The first is history.jsonl (%LOCALAPPDATA%\nms-direct-link on Windows): one compact line per new save (balances, counts, item totals, your location glyphs and the save's account folder name), so your assistant can tell you what changed. Delete it any time or set NMS_NO_HISTORY=1. Scanned shops live next to it in shops.sqlite; screenshots are never stored by the server. The test suite uses a fully synthetic save.

• No Man's Sky © Hello Games. This is an unofficial fan project and is not affiliated with or endorsed by Hello Games.

◆ Roadmap

Ideas on the board

• Auto-scan on dock. Watch the save for a station dock and prompt "want me to scan the shops?"

• Mission board reader. Scan the board and rank missions by nanite and units payout per minute.

• Route to the upgrade. Chain the upgrade plan into the route planner: "take me to the nearest scanned station with an S-class hyperdrive".

• Sell list. Once game data lands (0.4), "what in my inventory is worth the most at this terminal?"

• Expedition helper. Read the expedition milestone screen and track what's left.

• Phone companion. Ask from your phone through Claude's remote access while the game stays full-screen.

Not planned: anything that needs to read the running game's memory.

◆ Tech breakdown

Save format. save*.hg is a stream of LZ4 blocks, each with a 16-byte header (0xFEEDA1E5 magic, compressed size, decompressed size ≤ 512 KiB, reserved). Decompressed, it is one JSON document with every key replaced by a 3-character token. The mf_*.hg files are XXTEA-encrypted manifests and are not needed for reading.

De-obfuscation. Keys are restored with the mapping that ships with MBINCompiler (mapping.json, 1,505 entries for libMBIN 7.10.0.1, redistributed unmodified under src/nms_direct_link/data/ with its LGPL-3.0 licence text). The parser reports any key it could not map, so a new patch shows up as a count in --self-test instead of a crash.

Galaxy. Atlas (galaxy.py) builds every system and planet from discovery records. Planet biome is the low 16 bits of the record's second VP value, with bit 16 marking infested worlds; custom names come from DM.CN. Routes order stops with nearest-neighbour plus 2-opt, and with a warp range run Dijkstra over known systems so every hop fits; gaps known systems can't bridge fall back to a straight-line jump count. Distances use region coordinates, so two stars in the same region show as "same region".

Model. SaveSnapshot (save/model.py) is a tolerant typed view: every accessor degrades to empty when a key is missing. Upgrade modules are recognised from their ID (^UP_HYP4#4242 → family UP_HYP, tier 4 → S-class, seed 4242); the game regenerates module stats from that seed at runtime, so stats are not in the save. Discovery backlog counts only records owned by this save's own discovery identities.

Address math. UniverseAddress (save/address.py) handles the packed 64-bit form used by discoveries and bases (X 12 bits, Z 12, Y 8, galaxy 8, system 12, planet 4), portal glyphs (P SSS YY ZZZ XXX), signal-booster codes and voxel distances (400 ly per region).

Shop Scanner. shops.py finds the No Man's Sky window with the Win32 API and grabs it with Pillow ImageGrab (or reads Steam's F12 screenshot folder), downsizes to JPEG and returns it as an MCP image. Reading happens in your assistant's vision model, so there is no OCR engine to install. What it reads is stored with nms_log_shop in SQLite, keyed by the system address from your save.

Server. Official mcp Python SDK 2.x (MCPServer), stdio transport by default, stderr-only logging, Pydantic-validated inputs, read-only tool annotations, markdown and JSON responses. A SaveStore caches the parsed save and reloads when the file's mtime or size changes.

Layout.

src/nms_direct_link/
  server.py        core MCP tools, resources, CLI
  tools_more.py    galaxy, route, hangar, companion, progress tools
  galaxy.py        atlas of visited systems/planets, biome decode, route planner
  extras.py        stats, standing, trade log, wonders, companions, waypoints, timers
  history.py       session-history log + diffs (user cache only)
  store.py         newest-save selection + cache
  knowledge.py     curated, dated gameplay knowledge
  community.py     public community-mission API client
  save/
    locate.py      Steam/GOG/Proton save discovery, slot mapping
    decompress.py  LZ4 block stream
    mapping.py     key mapping load / download / (de)obfuscate
    address.py     galactic address math
    model.py       typed save view
  shops.py         Shop Scanner capture (window / Steam F12) + SQLite store
  tools_shops.py   Shop Scanner MCP tools
  planner.py       upgrade gaps, station brief, price memory
  tools_station.py station brief / upgrade plan / best prices tools
  data/            mapping.json (+ its LGPL-3.0 licence)
tests/             synthetic-fixture suite + optional real-save smoke test

Develop.

git clone https://github.com/Zeekeey-jpeg/No-Mans-Sky-Direct-Link && cd No-Mans-Sky-Direct-Link
python -m venv .venv && . .venv/Scripts/activate   # or source .venv/bin/activate
pip install -e ".[dev]"
ruff check . && pytest
NMS_SMOKE_SAVE="%APPDATA%\HelloGames\NMS\st_<id>\save.hg" pytest tests/test_real_save_smoke.py

Stack.

◆ Credits

• MBINCompiler / libMBIN by monkeyman192 — the key mapping and the decoded game structures (LGPL-3.0; mapping.json redistributed unmodified).

• NMS Copilot by oxur — the Rust save-reading MCP that proved the approach and documented the LZ4/XXTEA/address layout (Apache-2.0).

• libNOM.io and NomNom by zencq — save format constants and version arithmetic (GPL-3.0; constants only, no code reused).

• NMSCD and the No Man's Sky modding community — coordinate conventions and years of documentation.

• Assistant for No Man's Sky by Khaoz-Topsy — the public community-mission endpoint.

License

MIT — see LICENSE. No Man's Sky is a trademark of Hello Games Ltd.