# SatisfactoryMCP

Ask Claude about a Satisfactory factory. SatisfactoryMCP is an MCP server that reads the save
files on this PC and answers in chat: what runs, what stands still and why, what to build next
and how, planned with a real optimizer over the game's own recipe data and the recipes the
world has unlocked. A local web page draws the same world on a map. Everything runs on the
player's PC and only ever *reads* saves.

An unofficial fan tool for Satisfactory. Not affiliated with or endorsed by Coffee Stain Studios.
Satisfactory and game assets © Coffee Stain Studios AB.

## Ask Claude about the factory

Phrased however the player likes; Claude picks the tools. Four questions and what comes back:

> *How healthy is the steel factory? Anything blocked or starved?*

`factory_health` lists the machines that need action, grouped by state and cause, and tells a
line backed up into full storage (stock done) from a real blockage: a torn belt, a feed that
brings the wrong item, an output that leads nowhere.

> *Plan 20 Modular Frames a minute with what I have unlocked. What do I build?*

`plan_factory` solves over the unlocked recipes and answers with the buildings per recipe at
their clocks, the raw inputs, the power drawn and the belt or pipe each flow needs, warnings
first: a whole machine for a sliver of a rate, unused Somersloops, a byproduct with no outlet.
A setup that would strand a byproduct is reported infeasible, not overstated. The plan's handle
goes on to `plan_layout`, `commission_plan` and `diff_vs_save`.

> *Which hard drive should I open first?*

`hard_drives` ranks the unclaimed drives by what each alternate would save against the goals
and saved plans: machines and power off the bill, and need against supply.

> *Show the coal power plant on the map.*

`show_on_map` answers with a link into the local map, centred on it.

Every answer names the save it read and how old it is. All 49 tools, the prompts and the
resources: [docs/mcp-surface.md](docs/mcp-surface.md).

## Quick start

Needs **Python ≥ 3.11** with [uv](https://docs.astral.sh/uv/), and **a local Satisfactory
install** (Steam or Epic): recipes and rates come from the game's own data dump, so they stay
right when the game patches. **Node.js** only builds the page. Developed and tested on
Windows, where saves and the install are found on their own; elsewhere, set their paths
([configuration](packages/satisfactory-core/README.md#configuration)).

### Chat

```bash
git clone https://github.com/lukszi/SatisfactoryMCP.git
cd SatisfactoryMCP
uv sync
```

Register it in **Claude Code**, at user scope so it loads in any directory:

```bash
claude mcp add --scope user satisfactory -- uv run --directory "/path/to/SatisfactoryMCP" satisfactory-mcp
```

**Claude Desktop** (`claude_desktop_config.json`) and other stdio clients:

```json
{
  "mcpServers": {
    "satisfactory": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/SatisfactoryMCP", "satisfactory-mcp"]
    }
  }
}
```

Then open a new chat and ask. `satisfactory-mcp` finds the local server or starts one, so every
chat and the page share one process, which ends itself after 10 minutes unused. Its commands
(`stop`, `start`, `restart`, `status`): [docs/hosted-seams.md](docs/hosted-seams.md#lifecycle).
Updating: [docs/releasing.md](docs/releasing.md#updating-an-install); from 0.2:
[docs/upgrading-to-0.3.md](docs/upgrading-to-0.3.md).

### The page

Build the page once, or unzip a release's `static.zip` into
`packages/satisfactory-web/src/satisfactory_web/static/`; then cut the item and building icons
from the installed game (again after a game update):

```bash
cd packages/satisfactory-web/src/satisfactory_web/frontend
npm ci && npm run build
cd -
uv run --extra gen python tools/gen_item_icons.py
```

The page is at <http://127.0.0.1:8712>, served by the same process: the first chat starts it,
or `uv run satisfactory-mcp-web`. It binds to localhost on purpose, because the API answers with
the contents of the save folder and has no authentication. Base maps are made on its map studio
(`#maps`), which names any setup still missing.

### A page served elsewhere: the helper

The page also builds to run in the browser with no server
([docs/hosted-seams.md](docs/hosted-seams.md#browser-runtime)). Served from a site or from this
PC, it reaches the saves through `sf-companion`, the helper on the player's PC, which also
serves the tools to a chat:

```bash
uv run --package sf-companion sf-companion serve --server https://<site>
claude mcp add --scope user sf-companion -- uv run --directory "/path/to/SatisfactoryMCP" --package sf-companion sf-companion mcp --server https://<site>
```

For a page served from this PC, pass `--origin http://127.0.0.1:<port>` instead of `--server`.
`sf-companion import-local` brings the local app's factory names and plans over, and
`sf-companion claude-command` prints the Claude Code command line that loads the game channel,
for requests typed in the game (a preview). Every command, and installing the helper from a
release without a clone: [docs/companion.md](docs/companion.md).

## What it can do

- **Read the world:** power circuits in the game's terms, factories found and named from the
  save, machine health with causes, fluid head lift, inventory and crates, phases, research,
  hard drives, Power Shards and Somersloops.
- **Plan:** an LP/MILP optimizer over the game's recipes and the world's unlocks, byproducts
  balanced, with layouts, commissioning against the save, unlock ranking and build sites;
  saved plans keep their history and share as links, text or files
  ([docs/planning.md](docs/planning.md)).
- **Show it:** a page with the map, factories, power, progress, items, world and planner,
  following the saves live as the game writes them.
- **Answer in the game:** the helper's game channel passes requests from an in-game mod to a
  running Claude Code session and the answer back
  ([docs/companion.md](docs/companion.md#game-channel)).

## The map

Factories, belts, pipes, power and resource nodes drawn over a base map: the game's own artwork,
or a satellite, relief or terrain map rendered from the game's data by the map generators
([tools/mapgen/README.md](tools/mapgen/README.md)), lit by a live sun.

![The world map: factories, belts and power lines over a satellite base map, with region names](docs/media/map-overview.webp)

| | |
| --- | --- |
| ![A coal power plant up close: generators, water extractors, belts and pipes](docs/media/factory-closeup.webp) *A power plant up close: machines, belts, pipes, wires* | ![The terrain base map: hillshaded relief with water, power lines on top](docs/media/terrain-relief.webp) *The terrain map, shaded from the game's heightfield* |

## Docs and packages

| Document | Covers |
| --- | --- |
| [DESIGN.md](DESIGN.md) | the design spine and the index of every spec document |
| [docs/mcp-surface.md](docs/mcp-surface.md) | every tool, prompt and resource |
| [docs/planning.md](docs/planning.md) | the optimizer, layout and unlock ranking |
| [docs/spatial-and-map.md](docs/spatial-and-map.md) | coordinates, regions, selectors and the map |
| [docs/hosted-seams.md](docs/hosted-seams.md) | the one process, the shim, map links, the stores, the browser runtime |
| [docs/companion.md](docs/companion.md) | the helper: commands, install, the game channel |
| [docs/DEVELOPING.md](docs/DEVELOPING.md) | development setup, tests, architecture rules |
| [docs/releasing.md](docs/releasing.md) | versions, branches, updating, releases |
| [CHANGELOG.md](CHANGELOG.md) | what changed, with upgrade notes |

One uv workspace, nine wheels at one version; each package's README says how to use it alone:

| Package | Holds |
| --- | --- |
| [`pioneersav`](packages/pioneersav/README.md) | the save parser, standard library only |
| [`pioneerpak`](packages/pioneerpak/README.md) | readers for the game's asset container, for the map and data generators |
| [`satisfactory-core`](packages/satisfactory-core/README.md) | game data, saves, the domain and planner, the JSON API as plain calls |
| [`satisfactory-mcp-server`](packages/satisfactory-mcp/README.md) | the MCP tools, the stdio server, the shim |
| [`satisfactory-web`](packages/satisfactory-web/README.md) | the web API and the page |
| `satisfactory-mcp` (root) | the one process, its lifecycle, the console scripts |
| [`sf-companion`](packages/companion/README.md) | the helper on the player's PC |
| [`sf-records`](packages/records/README.md) | the helper's records file and edits API |
| [`sf-projection`](packages/projection/README.md) | a packed save projection's metadata |

## Licence

**[PolyForm Shield 1.0.0](LICENSE).** Free for any use except providing a product, paid or
free, that competes with this software or with any product the licensor provides using it.
Copies must carry the licence terms (or their URL) and the required notice:

> Required Notice: Copyright Lukas Szimtenings (https://github.com/lukszi/SatisfactoryMCP)
>
> Licensor Line of Business: Satisfactory save analysis, factory planning and map software
> and hosted services (https://github.com/lukszi/SatisfactoryMCP)

A competing product needs a separate licence from the licensor — get in touch via GitHub
([@lukszi](https://github.com/lukszi)). The licence covers this repository's code, tooling and
extracted tables; it cannot and does not grant anyone rights over the game's content, which
Coffee Stain Studios retains. The page bundles [Leaflet](https://leafletjs.com/)
(BSD-2-Clause) at build time, with its licence text beside every build.

Contributions are accepted under the [CLA](CLA.md); the steps are in
[CONTRIBUTING.md](CONTRIBUTING.md).