Factorio Planner MCP

简体中文

A community MCP server for asking accurate Factorio recipe and production questions in ChatGPT and other MCP clients. Uses pinned FactorioLab datasets and a deterministic GLPK material-balance solver.

With heartfelt thanks to FactorioLab

This project exists because of FactorioLab, created by Doug Broad / dcbroad3, and maintained with the help of its contributors.

From Dyson Sphere Program to Factorio, I have relied on FactorioLab's calculator to make sense of my factories. It has saved me more times than I can count. This MCP service is a small way to build on that work and make reliable calculations accessible in everyday AI conversations.

Thank you, Doug, and everyone who has contributed data, translations, code, bug reports, and maintenance. Please visit the original calculator and consider supporting its author through the links on the upstream project.

Factorio Planner MCP is independently maintained. It is not an official FactorioLab or Wube product. Original MIT copyright and license notices are retained in data/FACTORIOLAB-LICENSE; dataset commit and hashes are recorded in data/manifest.json.

Related MCP server: eve-fit

Use the hosted service

• MCP endpoint: https://factorio-mcp.anormlylee.com/mcp

• Homepage: https://factorio-mcp.anormlylee.com/

• Authentication: No authentication

• Transport: stateless Streamable HTTP

In ChatGPT, add a custom MCP server, paste the endpoint, create and install the plugin, then start a new Chat conversation and select it with @. Account/workspace permissions determine whether custom connections are available. See the official connection instructions. This project does not require a public ChatGPT directory listing for self-hosting or personal custom connections.

Try:

Use Factorio Planner to look up the recipes and allowed locations for promethium science packs and quantum processors. Calculate the quantum processors needed for 120 science packs per minute, then compare open-loop coolant input with a cooling loop.

Inspect the actual tool calls. Connecting a server does not guarantee that a model will choose the right tools on every turn. Optional conversation instructions are in examples/chatgpt-instructions.md.

The hosted service is a best-effort community endpoint. You can deploy your own copy using any method below. The server itself does not call an LLM and needs no OpenAI API key.

What it does

• Search English/Chinese names, IDs and selected aliases such as 黑瓶, 冷氟酮 and 地星.

• Inspect recipes, returned catalysts, machine producers, and both recipe and machine location restrictions.

• Calculate steady-state production networks with external inputs, byproducts and recycling loops.

• Apply machine base productivity, machine quality, speed/productivity modules and module quality, and supported productivity research.

• Report gross flows, boundary inputs, resource acquisition, surplus and fractional machine counts.

• Account for barrel filling/emptying and empty-barrel return; estimate minimum circulating barrels if a round-trip duration is provided.

Default dataset: 2x1 (Space Age 2.1 snapshot). Also bundled: 2.1, spa (Space Age 2.0), 2.0. Every result reports provenance. These are bundled snapshots, not detection of the user's Steam installation.

Self-host on Cloudflare Workers

Requirements: Node.js 22.18+ and a Cloudflare account.

git clone https://github.com/anormlylee/factorio-planner-mcp.git
cd factorio-planner-mcp
npm ci --ignore-scripts
npm run check
npx wrangler login
npm run deploy:self

deploy:self uses wrangler.self-host.jsonc, with no custom domain routes. Wrangler prints your own workers.dev hostname; append /mcp. To bind your own domain, add a route with custom_domain: true to that config. Do not reuse the maintainer's hostname in your account.

Local Worker development:

npm run dev:worker
# In a second terminal:
npm run test:worker

Workers use the same tools and calculation logic as Node. JSON datasets and GLPK WASM are bundled at build time. scripts/prepare-worker.js verifies dataset hashes and generates a compatibility adapter from pinned GLPK.js 5.0.0. It does not change the optimization model or solver mathematics. Details: docs/worker-adapter.md.

The Worker has an IP-based limit of 120 MCP requests/minute and a 100 KiB request body limit. Cloudflare plan CPU, memory, request and billing limits still apply; broad automatic production chains may need more CPU than focused recipe queries. Deployment does not purchase or upgrade a Cloudflare plan. No database, container subscription, secrets or LLM account is required by this implementation.

Self-host with Docker

git clone https://github.com/anormlylee/factorio-planner-mcp.git
cd factorio-planner-mcp
docker compose up -d --build

The service listens at http://127.0.0.1:3000/mcp. Put your own HTTPS reverse proxy in front of it for remote ChatGPT use. Set ALLOWED_HOSTS to your own hostname(s), without schemes or ports, and preserve the Host header at your proxy. The optional settings are shown in .env.example.

The Node prototype uses a per-connection-source memory rate limit. Users behind the same reverse proxy may share it; configure appropriate edge/proxy limits for a public installation. The Cloudflare Worker uses the platform rate limiter keyed by the connecting client IP.

Run locally or over stdio

npm ci --ignore-scripts
npm start
# Or:
npm run start:stdio

A local stdio client can use:

{
  "mcpServers": {
    "factorio-planner": {
      "command": "node",
      "args": ["/absolute/path/to/factorio-planner-mcp/src/stdio.js"]
    }
  }
}

Stdio and localhost are for clients that can access that machine. A remote ChatGPT connection requires reachable HTTPS or a separately configured supported secure tunnel.

Calculation example

{
  "targets": {"quantum-processor": 12},
  "location": "aquilo",
  "recipeIds": ["quantum-processor", "fluoroketone-cooling"],
  "externalInputs": ["fluoroketone-cold"]
}

The baseline uses normal-quality products, no modules/research, and the first producer valid at the specified location, including its inherent productivity. For this network, cold coolant is consumed at 80/minute, regenerated at 40/minute and imported at 40/minute. Returned hot coolant is not multiplied by productivity. npm run example generates the complete worked example.

targets defaults to per-minute; rateUnit also accepts second and hour. Output always uses per-minute. recipeIds limits the exact recipe network; missing upstream ingredients become boundary inputs. Without it, the solver expands upstream recipes. externalInputs stops automatic upstream expansion, while explicit recipes can still regenerate those inputs in loops.

Optional per-recipe settings:

{
  "settings": {
    "quantum-processor": {
      "machine": "electromagnetic-plant",
      "quality": "legendary",
      "modules": [{"id": "productivity-module-3", "quality": "legendary", "count": 5}]
    }
  }
}

quality here describes machines/modules; products remain normal quality. Calls are stateless: repeat the user's prior settings on follow-up calculations. get_recipe lists whether the recipe supports a research productivity bonus.

Scope and limitations

• Results are recipe material balances, not a complete factory utility or transport budget. Energy, fuel/food, heat, spoilage timing, technology progression and rocket/platform logistics costs are excluded. FUEL_NOT_INCLUDED warns about affected machines.

• inputs are boundary imports. acquisition lists mining/pumping/other recipes with no recipe ingredients; do not omit those resource sources or describe food-powered machines as requiring no supplies.

• Recipe and machine location conflicts are rejected. Without location, the network may span multiple locations; it must not be described as a single-planet build.

• No beacon effects, quality-module random outputs, mining research/depletion, or full logistics simulation. Unknown startup inventory is null.

• Optimization first minimizes weighted boundary inputs (fluid weight 0.1), then base recipe time. It is not a construction, energy, or transport cost optimum.

• The headless adapter follows FactorioLab's net-balance and catalyst rules but is not a complete port of the Angular application. Critical scenarios have tests; full upstream feature parity has not been established.

Development and data maintenance

npm run check
npm run build:worker
npm run example
npm audit
node scripts/smoke-http.js https://YOUR-HOST/mcp

To update the bundled data, explicitly select a reviewed upstream commit:

npm run sync:data -- UPSTREAM_40_CHARACTER_COMMIT_SHA
npm run check
npm run build:worker
npm run example

The sync command downloads all snapshots and translations before replacing files, retains upstream licensing, and updates the manifest. Review the diff and calculation changes before committing. It does not automatically change datasets at runtime.

Bug reports and contributions are welcome. Include the question, exact tool input/output and dataset provenance, without private chat history or credentials. CI tests Node and the actual local Workers runtime. No deployment credentials are stored in this repository.

License

GPL-3.0-only for this project, including its GLPK.js integration. FactorioLab datasets/translations retain the upstream MIT license. See LICENSE, THIRD_PARTY_NOTICES.md and the retained FactorioLab license.