FactorioMCP

FactorioMCP

An MCP (Model Context Protocol) server that connects to a running Factorio game via RCON and lets an AI agent play the game realistically — walking, crafting, building — without cheating.

LLM (Claude/GPT/etc) ←→ [MCP Server (C#, stdio)] ←→ [RCON TCP] ←→ Factorio Game

Key Principle

The AI player does not cheat. It walks to locations using real game physics, waits for crafting to finish, and only interacts with entities within range. No teleportation, no spawning items, no skipping time.

Prerequisites

• .NET 9 SDK
• Factorio (any edition that supports RCON)

Setup

1. Launch Factorio with RCON

Singleplayer:

factorio.exe --rcon-port 27015 --rcon-password mypassword

Dedicated server:

factorio --start-server save.zip --rcon-port 27015 --rcon-password mypassword

2. Configure Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | FACTORIO_RCON_HOST | 127.0.0.1 | RCON server host | | FACTORIO_RCON_PORT | 27015 | RCON server port | | FACTORIO_RCON_PASSWORD | mypassword | RCON password | | FACTORIO_GOALS_FILE | goals.json | File path for goal planner persistence | | FACTORIO_BUILDINGS_FILE | buildings.json | File path for building memory persistence |

3. Build

dotnet build

Connecting an MCP Client

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "factorio": {
      "command": "dotnet",
      "args": ["run", "--project", "path/to/FactorioMCP"],
      "env": {
        "FACTORIO_RCON_PASSWORD": "mypassword"
      }
    }
  }
}

VS Code (GitHub Copilot)

A pre-configured [.vscode/mcp.json](.vscode/mcp.json) is included in the repository. Open the workspace in VS Code and it will be detected automatically. Adjust the environment variables if needed.

Manual setup

Add to your .vscode/mcp.json:

{
  "servers": {
    "factorio": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "${workspaceFolder}/FactorioMCP"],
      "env": {
        "FACTORIO_RCON_HOST": "127.0.0.1",
        "FACTORIO_RCON_PORT": "27015",
        "FACTORIO_RCON_PASSWORD": "mypassword"
      }
    }
  }
}

LM Studio (Local Models)

LM Studio can connect to MCP servers via its built-in MCP client. This is a good option for running a local model without cloud API costs.

1. Install LM Studio and download a model (recommended: qwen3-32b or similar with tool-calling support).

1. Enable MCP in LM Studio: go to Settings → MCP (or the MCP tab in the chat sidebar).

1. Add the FactorioMCP server with this configuration:

``json { "factorio": { "command": "dotnet", "args": ["run", "--project", "path/to/FactorioMCP"], "env": { "FACTORIO_RCON_HOST": "127.0.0.1", "FACTORIO_RCON_PORT": "27015", "FACTORIO_RCON_PASSWORD": "mypassword" } } } ``

1. Start a chat with the model — tools will appear in the MCP tools panel. The model will call tools to interact with Factorio.

> Note: Local models may have weaker tool-calling compared to cloud models. If the model struggles to use tools correctly, try a larger parameter model or one specifically fine-tuned for function calling.

Available Tools

> Full reference: See [TOOLS.md](TOOLS.md) for detailed parameters, return values, and AI prompt engineering tips.

Movement

| Tool | Description | |------|-------------| | WalkForDuration | Walk in a direction for N seconds, then stop. Returns position after walking. | | StopWalking | Stop the player from walking immediately. | | GetPlayerPosition | Get the player's current map position. |

Inventory & Crafting

| Tool | Description | |------|-------------| | GetInventory | List all items and counts in the player's main inventory. | | Craft | Begin crafting items using a recipe. Respects real crafting time. | | GetCraftingQueue | Get the current crafting queue contents. |

Entity Placement & Mining

| Tool | Description | |------|-------------| | PlaceEntity | Place an entity from inventory at map coordinates (with direction). Automatically tracked in building memory. | | MineEntity | Mine/remove an entity at map coordinates into inventory. Automatically untracked from building memory. |

Entity Interaction

| Tool | Description | |------|-------------| | InsertItems | Insert items from player inventory into a machine (fuel, ore, etc.). | | RemoveItems | Remove items from a machine's inventory into player inventory. | | InspectEntity | Inspect entity status, inventories, fuel, recipe, and health. |

World Scanning

| Tool | Description | |------|-------------| | GetNearbyEntities | List all entities near the player within a given radius. | | CheckDistance | Check distance to coordinates and whether within build/reach range. | | ScanResources | Scan for resource patches (ores, oil) with type summaries and center coordinates. | | ScanTiles | Scan terrain tiles for type counts (grass, sand, water, etc.). |

Wait & Polling

| Tool | Description | |------|-------------| | WaitForCrafting | Wait for the crafting queue to empty. | | WaitForPosition | Wait until the player reaches target coordinates. | | WaitForTicks | Wait for a specified number of game ticks to elapse. | | GetGameTick | Get the current game tick. |

Chat

| Tool | Description | |------|-------------| | InitializeChatListener | Initialize/re-initialize the chat message event listener. | | GetChatMessages | Get chat messages from the in-game chat log (with polling support). | | SendChatMessage | Send an [AI]-tagged chat message visible to all players. |

Goal Planning

| Tool | Description | |------|-------------| | SetGoal | Create a new goal with optional ordered steps. | | GetActiveGoal | Get the currently active goal with step details. | | GetAllGoals | Get a summary of all goals (completed, failed, suspended, pending). | | AdvanceGoalStep | Mark the current step as completed and advance. | | AddGoalSteps | Add new steps to the active goal. | | CompleteGoal | Mark the active goal as completed. | | FailGoal | Mark the active goal as failed with a reason. | | SuspendGoal | Suspend the active goal to work on something urgent. | | ResumeGoal | Resume a previously suspended goal. |

Energy

| Tool | Description | |------|-------------| | GetElectricNetwork | Get electric network stats: production, consumption, satisfaction, accumulators. | | InspectEntityPower | Inspect per-entity power status: connection, energy, buffer, drain. |

Research

| Tool | Description | |------|-------------| | GetResearchStatus | Get current research technology and progress percentage. | | GetAvailableTechnologies | List all technologies available for research (prerequisites met). | | StartResearch | Start researching a technology. |

Recipe & Technology Queries

| Tool | Description | |------|-------------| | GetRecipeDetails | Get recipe ingredients, products, crafting time, and category. | | GetAvailableRecipes | List all currently unlocked recipes. | | GetTechnologyDetails | Get technology prerequisites, effects, cost, and ingredients. |

Building Memory

| Tool | Description | |------|-------------| | GetAllBuildings | Get all tracked buildings with names, positions, directions, and labels. | | GetBuildingsNear | Get tracked buildings near a position within a radius. | | FindBuildingsByType | Find all tracked buildings of a specific entity type. | | GetBuildingSummary | Get counts of each tracked building type. | | UpdateBuildingLabel | Set or remove a label on a tracked building. | | ClearBuildingMemory | Clear all tracked buildings from AI memory (not from game world). |

Blueprints & Ghosts

| Tool | Description | |------|-------------| | PlaceGhostEntity | Place a ghost (construction plan) for an entity at map coordinates. | | PlaceBlueprintString | Import and build a blueprint string at a position. | | GetGhostEntities | Scan for ghost entities in an area. | | CreateBlueprintFromArea | Capture an area as an exportable blueprint string. | | RevokeGhostEntity | Remove a ghost entity at a position. |

Advanced

| Tool | Description | |------|-------------| | ExecuteLua | Execute arbitrary Lua code via RCON. Use for advanced operations not covered by other tools. |

Project Structure

FactorioMCP/
├── Program.cs                          # Host setup, DI, MCP server wiring
├── Rcon/
│   ├── RconClient.cs                   # Source RCON protocol over TCP
│   └── RconPacket.cs                   # RCON packet types and record
├── Models/
│   ├── Goal.cs                         # Goal/step data model
│   └── TrackedBuilding.cs              # Building memory data model
├── Services/
│   ├── FactorioService.cs              # High-level game operations via Lua
│   ├── EnergyService.cs                # Electric network inspection via Lua
│   ├── BlueprintService.cs             # Blueprint and ghost entity operations
│   ├── GoalPlannerService.cs           # Goal tracking with JSON persistence
│   ├── BuildingMemoryService.cs        # Building tracking with JSON persistence
│   ├── GameCommandQueue.cs             # Serializes concurrent MCP tool calls
│   └── RconConnectionService.cs        # RCON connection on startup
├── Tools/
│   ├── MovementTools.cs                # Walk, stop, get position
│   ├── InventoryTools.cs               # Inventory, crafting
│   ├── EntityTools.cs                  # Place/mine entities
│   ├── InteractionTools.cs             # Insert/remove items, inspect entities
│   ├── WorldTools.cs                   # Nearby entities, distance, scan
│   ├── WaitTools.cs                    # Wait for crafting, position, ticks
│   ├── ChatTools.cs                    # Chat message listener, send/receive
│   ├── GoalTools.cs                    # Goal planning and tracking
│   ├── EnergyTools.cs                  # Electric network and power inspection
│   ├── ResearchTools.cs                # Research status, start research
│   ├── RecipeTools.cs                  # Recipe and technology queries
│   ├── BuildingTools.cs                # Building memory queries
│   ├── BlueprintTools.cs               # Blueprint and ghost entity tools
│   └── LuaTools.cs                     # Raw Lua execution
└── Resources/
    └── GameStateResources.cs           # MCP Resources (read-only game state)

FactorioMCP.Tests/                      # Unit tests (xUnit)

Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow guidelines, CPX complexity scale, and coding conventions.

License

See repository for license details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sbarisic
• Source: sbarisic/FactorioMCP
• License: MIT

Install and usage instructions live in the source repository linked above.