CraftGenie for developers and AI assistants

CraftGenie is a free crafting database and factory planner for crafting and automation games. Its data and its planner are open to your code and your AI assistant in two ways: a remote MCP server, and a JSON REST API. Neither needs a key to read or to plan.

• MCP server (Streamable HTTP): https://craftgenie.io/mcp
• REST API index: https://craftgenie.io/api/v1
• OpenAPI document: https://craftgenie.io/api/v1/openapi.json
• These docs as markdown: https://craftgenie.io/developers.md

Plan links: a factory from a URL, no tools needed

An assistant with no tools, or one that can only fetch a page, can still hand its user a whole planned factory: write a plan link. Opening it runs the same planner as POST /api/v1/plan, keeps the plan, and redirects to its short /p/… page, read-only with its graph, production and power, ready to copy into the user’s own factory.

https://craftgenie.io/plan/{game}?make={item}:{amount},{item}:{amount}

A working one, ready to copy (several targets in one link):

https://craftgenie.io/plan/satisfactory?make=heavy-modular-frame:10/min,computer:10/min,supercomputer:4/min

Each game’s page (/games/{game}/factory) and its markdown (/games/{game}.md) list item slugs to plan, with a working link for that game, under “For AI assistants”.

• game: the game’s slug from GET /api/v1/games (factorio, core-keeper). Its name works too (Factorio, core keeper, dsp).
• make: what to make, item:amount, comma-separated, up to 20. The item is its slug (electronic-circuit) or its name: case, spaces or underscores, plurals and small typos are forgiven.
• amount: 60/min (or /s, /h) is a rate; a bare 60 is a total. When any target has a rate, bare numbers are per minute too. Leave it out for 1: a minute in factory games, in total in batch games such as Palworld.
• prefer, allow, block (optional): recipes by key or name, comma-separated, as in POST /api/v1/plan; allow=all allows every alternate recipe.
• mode=rate or mode=total (optional): how bare numbers read. energy=off (optional): leave power and fuel out.
• A link that resolves redirects to the plan’s short /p/… page, the same plan and the same link POST /api/v1/plan gives for that body. One that does not (an unknown or ambiguous name) opens a “Did you mean…?” page that links the corrected plan links.

Names are forgiving, so a link written from memory usually works: Electronic Circuits, electronic_circuit and electronic-circuit are the same item, and Factorio the same game as factorio. Use slugs where you have them. The same link is always the same plan, plans count against the plan limit below, and plan links are never indexed. Examples:

• Satisfactory: 10 heavy modular frames, 10 computers and 4 supercomputers a minute: https://craftgenie.io/plan/satisfactory?make=heavy-modular-frame:10/min,computer:10/min,supercomputer:4/min
• Factorio: 60 electronic circuits a minute: https://craftgenie.io/plan/factorio?make=electronic-circuit:60/min
• Factorio: two targets, by name, one a second: https://craftgenie.io/plan/factorio?make=Automation_Science_Pack:1/s,iron-gear-wheels:30/min
• Factorio: plastic from advanced oil processing, without power: https://craftgenie.io/plan/factorio?make=plastic-bar:30/min&prefer=advanced-oil-processing&energy=off
• Satisfactory: computers and heavy modular frames, every alternate allowed: https://craftgenie.io/plan/satisfactory?make=computer:5/min,heavy-modular-frame:2/min&allow=all
• Satisfactory: 60 iron plates a minute: https://craftgenie.io/plan/satisfactory?make=iron-plate:60/min
• Palworld: 100 Pal Spheres (a total): https://craftgenie.io/plan/palworld?make=pal-sphere:100
• Palworld: 50 nails and 20 ingots: https://craftgenie.io/plan/palworld?make=nails:50,ingot:20
• Dyson Sphere Program: 30 processors a minute: https://craftgenie.io/plan/dyson-sphere-program?make=processor:30/min
• Core Keeper: 20 copper bars: https://craftgenie.io/plan/core-keeper?make=copper-bar:20

Quick start for AI assistants

• If you can use MCP tools, connect https://craftgenie.io/mcp and call plan_factory, search_items and the rest (below).
• If you can only make HTTP requests, find item slugs with GET /api/v1/games/{game}/items?q= and plan with POST /api/v1/plan.
• If you cannot call tools or send a POST at all, write a plan link yourself: https://craftgenie.io/plan/factorio?make=electronic-circuit:60/min plans the factory and opens it (below).
• Every plan answer carries open_url, a short link that opens the plan as an interactive factory on CraftGenie. Give it to your user with the plan.
• Credit the data with the license.attribution text of every answer about a game, and respect commercial_use.

MCP server

CraftGenie is a remote MCP server, so an assistant can look up recipes and plan factories itself, and hand you a link to the interactive graph. It speaks Streamable HTTP at:

https://craftgenie.io/mcp

Every tool works without a key except create_share_link, which saves to the account a key belongs to. Clients that cannot send a header (Claude.ai and ChatGPT connectors) get every other tool, and plan_factory’s open_url still hands you the interactive factory.

Claude Code

claude mcp add --transport http craftgenie https://craftgenie.io/mcp

With a key, for saved share links:

claude mcp add --transport http craftgenie https://craftgenie.io/mcp \
  --header "Authorization: Bearer cg_…"

Claude.ai and Claude Desktop

Settings → Connectors → Add custom connector. Name it CraftGenie and give the URL https://craftgenie.io/mcp.

ChatGPT

Settings → Apps & Connectors → Advanced settings → turn on Developer mode, then Create a connector with the URL https://craftgenie.io/mcp and no authentication.

Cursor

In .cursor/mcp.json (or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "craftgenie": {
      "url": "https://craftgenie.io/mcp",
      "headers": {
        "Authorization": "Bearer cg_…"
      }
    }
  }
}

Leave out headers to use it without a key.

The REST API

A read-only JSON API over every game’s items and recipes, and the planner that fills a whole production chain. It is versioned at /api/v1: nothing in it changes in a way that breaks a client, and a breaking change would be /api/v2. The full contract is the OpenAPI document.

Games and items are named by slug, as the site’s addresses name them. Recipes are named by id, or by their key where the game’s data gives one. Lists take page and limit (up to 100). No key is needed to read.

List the games

curl 'https://craftgenie.io/api/v1/games'

Find an item

curl 'https://craftgenie.io/api/v1/games/factorio/items?q=circuit'

What makes an item, and what uses it

curl 'https://craftgenie.io/api/v1/games/factorio/items/electronic-circuit'

One recipe, by key or id

curl 'https://craftgenie.io/api/v1/games/factorio/recipes/advanced-oil-processing'

Planning a factory: POST /api/v1/plan

POST /api/v1/plan runs CraftGenie’s own planner, the one behind every factory on the site: it picks a recipe for each part of the chain (or uses the ones you prefer), sizes every machine, powers each grid and balances by-products. The body is JSON:

• game: the game’s slug (see GET /api/v1/games).
• targets: [{ item, rate }] in items a minute, or [{ item, quantity }] for a total (batch games), up to 20. item is the item’s slug.
• options.mode: perMinute or total; by default, what the targets give.
• options.recipes: prefer, recipes to use first; allow, unlockable (alternate) recipes the player has, or "all"; block, recipes not to use.
• options.grids: power grids, Main first, each with the items or stations it powers and, if you like, its generator and fuel.
• options.energy: false leaves fuel and power out.

Example: 60 electronic circuits a minute

curl -X POST 'https://craftgenie.io/api/v1/plan' \
  -H 'Content-Type: application/json' \
  -d '{"game":"factorio","targets":[{"item":"electronic-circuit","rate":60}]}'

The request body:

{
  "game": "factorio",
  "targets": [
    {
      "item": "electronic-circuit",
      "rate": 60
    }
  ]
}

The answer, abbreviated (entries, machines and license hold more than shown):

{
  "game": "factorio",
  "open_url": "https://craftgenie.io/p/abc123defg",
  "mode": "perMinute",
  "per": "per minute",
  "targets": [
    {
      "item": "electronic-circuit",
      "name": "Electronic Circuit",
      "asked": 60,
      "amount": 60
    }
  ],
  "summary": {
    "text": "Electronic Circuit 60/min in Factorio: 10 recipes on 28 machines. Raw inputs: none. Power: Main 195 / 900 kW.",
    "met": true,
    "scale": null,
    "recipes": 10,
    "machines": 28,
    "problems": []
  },
  "entries": [
    {
      "recipe": {
        "id": "…",
        "key": "electronic-circuit",
        "name": "Electronic Circuit"
      },
      "station": {
        "item": "assembling-machine-1",
        "name": "Assembling Machine 1"
      },
      "machines": 1,
      "built": 1,
      "crafts": 60,
      "seconds": 1,
      "grid": "Main",
      "outputs": [
        {
          "item": "electronic-circuit",
          "name": "Electronic Circuit",
          "amount": 60
        }
      ],
      "inputs": [
        {
          "item": "iron-plate",
          "name": "Iron Plate",
          "amount": 60,
          "consumed": true
        },
        {
          "item": "copper-cable",
          "name": "Copper Cable",
          "amount": 180,
          "consumed": true
        }
      ],
      "power": 0.075
    }
  ],
  "machines": [
    {
      "item": "burner-mining-drill",
      "name": "Burner Mining Drill",
      "count": 13
    },
    {
      "item": "stone-furnace",
      "name": "Stone Furnace",
      "count": 9
    }
  ],
  "raw_inputs": [],
  "surplus": [],
  "power": [
    {
      "grid": "Main",
      "unit": "MW",
      "text": "195 / 900 kW",
      "used": 0.195,
      "capacity": 0.9
    }
  ],
  "license": {
    "game": "factorio",
    "commercial_use": true,
    "license": "MIT",
    "attribution": "…"
  }
}

The answer holds a summary (one line of text, whether the targets are met, and any problems), every recipe in the chain with its machines, crafts, inputs and outputs, the machines to build, the raw inputs, the surplus, the power on each grid, and the game’s license.

It also holds open_url, a short link (/p/…) that opens this exact factory in CraftGenie as a read-only page, with its graph, production and power, that the visitor can explore and copy into their own factory to change and save. It needs no key and belongs to no account. The same plan always gets the same link, and a link nobody opens for 90 days expires. POST /api/v1/shares takes the same body (and a name) and saves the plan as a permanent share page on your account instead.

Plans that people open from their link may be listed publicly among the factories people are planning (GET /api/v1/plans?sort=popular|new&game=). Only an open of the /p/… page in a browser counts, once per visitor a day; reading a plan through the API does not. A plan holds only game data (items, recipes and rates), never your users’ words.

Keys and limits

Reads and plans need no key. A key raises your limits and lets you save share links. Make one on your account page and send it as Authorization: Bearer cg_…. A wrong or revoked key is refused (401), never treated as anonymous.

A plan’s body is at most 32 KB, with up to 8 grids, and runs for at most 10 seconds. Anonymous limits count per address, keyed ones per key; every answer says how much is left in X-RateLimit-Remaining.

Licensing

Each game has its own data license. Every answer about a game carries it in license: credit the data with attribution, and where commercial_use is false, use the data for non-commercial purposes only, under terms.

Non-commercial use only means you may not use the data in anything primarily meant for commercial advantage or money. Where share_alike is true, share what you build from the data under the same license.

Some games on the site are not available through the API or the MCP server, because their data cannot be licensed for reuse. Game names and content are trademarks and copyrights of their owners; CraftGenie is an unofficial fan tool. The site’s attributions list every game’s owners and sources.

Errors and caching

Every error has one shape: { "error": { "code", "message", "issues"? } }. The codes are NOT_FOUND (also for a game the API does not serve), VALIDATION (400, with issues naming each problem), UNAUTHENTICATED (401), RATE_LIMITED (429, with Retry-After), PAYLOAD_TOO_LARGE (413), and PLAN_BUSY or PLAN_TIMEOUT (503, with Retry-After).

Reads are cacheable for five minutes and carry an ETag: send it back in If-None-Match for a 304. CORS is open to every origin, and no request uses cookies, so the API works from a browser page as well as a server.