{"id":48581319,"url":"https://github.com/sbarisic/factoriomcp","last_synced_at":"2026-04-08T17:01:22.485Z","repository":{"id":348723926,"uuid":"1198523048","full_name":"sbarisic/FactorioMCP","owner":"sbarisic","description":"FactorioMCP that allows LLMs to play the game","archived":false,"fork":false,"pushed_at":"2026-04-02T15:46:35.000Z","size":4908,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-03T02:43:55.369Z","etag":null,"topics":["factorio","factorio-tool","factorio-tools","mcp"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sbarisic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T13:59:52.000Z","updated_at":"2026-04-02T15:46:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sbarisic/FactorioMCP","commit_stats":null,"previous_names":["sbarisic/factoriomcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sbarisic/FactorioMCP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbarisic%2FFactorioMCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbarisic%2FFactorioMCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbarisic%2FFactorioMCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbarisic%2FFactorioMCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sbarisic","download_url":"https://codeload.github.com/sbarisic/FactorioMCP/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbarisic%2FFactorioMCP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31564915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["factorio","factorio-tool","factorio-tools","mcp"],"created_at":"2026-04-08T17:01:21.443Z","updated_at":"2026-04-08T17:01:22.476Z","avatar_url":"https://github.com/sbarisic.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FactorioMCP\n\nAn 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.\n\n```\nLLM (Claude/GPT/etc) ←→ [MCP Server (C#, stdio)] ←→ [RCON TCP] ←→ Factorio Game\n```\n\n## Key Principle\n\nThe 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.\n\n## Prerequisites\n\n- [.NET 9 SDK](https://dotnet.microsoft.com/download/dotnet/9.0)\n- [Factorio](https://factorio.com/) (any edition that supports RCON)\n\n## Setup\n\n### 1. Launch Factorio with RCON\n\n**Singleplayer:**\n```sh\nfactorio.exe --rcon-port 27015 --rcon-password mypassword\n```\n\n**Dedicated server:**\n```sh\nfactorio --start-server save.zip --rcon-port 27015 --rcon-password mypassword\n```\n\n### 2. Configure Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `FACTORIO_RCON_HOST` | `127.0.0.1` | RCON server host |\n| `FACTORIO_RCON_PORT` | `27015` | RCON server port |\n| `FACTORIO_RCON_PASSWORD` | `mypassword` | RCON password |\n| `FACTORIO_GOALS_FILE` | `goals.json` | File path for goal planner persistence |\n| `FACTORIO_BUILDINGS_FILE` | `buildings.json` | File path for building memory persistence |\n\n### 3. Build\n\n```sh\ndotnet build\n```\n\n## Connecting an MCP Client\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"factorio\": {\n      \"command\": \"dotnet\",\n      \"args\": [\"run\", \"--project\", \"path/to/FactorioMCP\"],\n      \"env\": {\n        \"FACTORIO_RCON_PASSWORD\": \"mypassword\"\n      }\n    }\n  }\n}\n```\n\n### VS Code (GitHub Copilot)\n\nA 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.\n\n\u003cdetails\u003e\n\u003csummary\u003eManual setup\u003c/summary\u003e\n\nAdd to your `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"factorio\": {\n      \"type\": \"stdio\",\n      \"command\": \"dotnet\",\n      \"args\": [\"run\", \"--project\", \"${workspaceFolder}/FactorioMCP\"],\n      \"env\": {\n        \"FACTORIO_RCON_HOST\": \"127.0.0.1\",\n        \"FACTORIO_RCON_PORT\": \"27015\",\n        \"FACTORIO_RCON_PASSWORD\": \"mypassword\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n### LM Studio (Local Models)\n\n[LM Studio](https://lmstudio.ai/) 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.\n\n1. **Install LM Studio** and download a model (recommended: `qwen3-32b` or similar with tool-calling support).\n\n2. **Enable MCP** in LM Studio: go to **Settings → MCP** (or the MCP tab in the chat sidebar).\n\n3. **Add the FactorioMCP server** with this configuration:\n\n   ```json\n   {\n     \"factorio\": {\n       \"command\": \"dotnet\",\n       \"args\": [\"run\", \"--project\", \"path/to/FactorioMCP\"],\n       \"env\": {\n         \"FACTORIO_RCON_HOST\": \"127.0.0.1\",\n         \"FACTORIO_RCON_PORT\": \"27015\",\n         \"FACTORIO_RCON_PASSWORD\": \"mypassword\"\n       }\n     }\n   }\n   ```\n\n4. **Start a chat** with the model — tools will appear in the MCP tools panel. The model will call tools to interact with Factorio.\n\n\u003e **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.\n\n## Available Tools\n\n\u003e **Full reference**: See [TOOLS.md](TOOLS.md) for detailed parameters, return values, and AI prompt engineering tips.\n\n### Movement\n\n| Tool | Description |\n|------|-------------|\n| `WalkForDuration` | Walk in a direction for N seconds, then stop. Returns position after walking. |\n| `StopWalking` | Stop the player from walking immediately. |\n| `GetPlayerPosition` | Get the player's current map position. |\n\n### Inventory \u0026 Crafting\n\n| Tool | Description |\n|------|-------------|\n| `GetInventory` | List all items and counts in the player's main inventory. |\n| `Craft` | Begin crafting items using a recipe. Respects real crafting time. |\n| `GetCraftingQueue` | Get the current crafting queue contents. |\n\n### Entity Placement \u0026 Mining\n\n| Tool | Description |\n|------|-------------|\n| `PlaceEntity` | Place an entity from inventory at map coordinates (with direction). Automatically tracked in building memory. |\n| `MineEntity` | Mine/remove an entity at map coordinates into inventory. Automatically untracked from building memory. |\n\n### Entity Interaction\n\n| Tool | Description |\n|------|-------------|\n| `InsertItems` | Insert items from player inventory into a machine (fuel, ore, etc.). |\n| `RemoveItems` | Remove items from a machine's inventory into player inventory. |\n| `InspectEntity` | Inspect entity status, inventories, fuel, recipe, and health. |\n\n### World Scanning\n\n| Tool | Description |\n|------|-------------|\n| `GetNearbyEntities` | List all entities near the player within a given radius. |\n| `CheckDistance` | Check distance to coordinates and whether within build/reach range. |\n| `ScanResources` | Scan for resource patches (ores, oil) with type summaries and center coordinates. |\n| `ScanTiles` | Scan terrain tiles for type counts (grass, sand, water, etc.). |\n\n### Wait \u0026 Polling\n\n| Tool | Description |\n|------|-------------|\n| `WaitForCrafting` | Wait for the crafting queue to empty. |\n| `WaitForPosition` | Wait until the player reaches target coordinates. |\n| `WaitForTicks` | Wait for a specified number of game ticks to elapse. |\n| `GetGameTick` | Get the current game tick. |\n\n### Chat\n\n| Tool | Description |\n|------|-------------|\n| `InitializeChatListener` | Initialize/re-initialize the chat message event listener. |\n| `GetChatMessages` | Get chat messages from the in-game chat log (with polling support). |\n| `SendChatMessage` | Send an `[AI]`-tagged chat message visible to all players. |\n\n### Goal Planning\n\n| Tool | Description |\n|------|-------------|\n| `SetGoal` | Create a new goal with optional ordered steps. |\n| `GetActiveGoal` | Get the currently active goal with step details. |\n| `GetAllGoals` | Get a summary of all goals (completed, failed, suspended, pending). |\n| `AdvanceGoalStep` | Mark the current step as completed and advance. |\n| `AddGoalSteps` | Add new steps to the active goal. |\n| `CompleteGoal` | Mark the active goal as completed. |\n| `FailGoal` | Mark the active goal as failed with a reason. |\n| `SuspendGoal` | Suspend the active goal to work on something urgent. |\n| `ResumeGoal` | Resume a previously suspended goal. |\n\n### Energy\n\n| Tool | Description |\n|------|-------------|\n| `GetElectricNetwork` | Get electric network stats: production, consumption, satisfaction, accumulators. |\n| `InspectEntityPower` | Inspect per-entity power status: connection, energy, buffer, drain. |\n\n### Research\n\n| Tool | Description |\n|------|-------------|\n| `GetResearchStatus` | Get current research technology and progress percentage. |\n| `GetAvailableTechnologies` | List all technologies available for research (prerequisites met). |\n| `StartResearch` | Start researching a technology. |\n\n### Recipe \u0026 Technology Queries\n\n| Tool | Description |\n|------|-------------|\n| `GetRecipeDetails` | Get recipe ingredients, products, crafting time, and category. |\n| `GetAvailableRecipes` | List all currently unlocked recipes. |\n| `GetTechnologyDetails` | Get technology prerequisites, effects, cost, and ingredients. |\n\n### Building Memory\n\n| Tool | Description |\n|------|-------------|\n| `GetAllBuildings` | Get all tracked buildings with names, positions, directions, and labels. |\n| `GetBuildingsNear` | Get tracked buildings near a position within a radius. |\n| `FindBuildingsByType` | Find all tracked buildings of a specific entity type. |\n| `GetBuildingSummary` | Get counts of each tracked building type. |\n| `UpdateBuildingLabel` | Set or remove a label on a tracked building. |\n| `ClearBuildingMemory` | Clear all tracked buildings from AI memory (not from game world). |\n\n### Blueprints \u0026 Ghosts\n\n| Tool | Description |\n|------|-------------|\n| `PlaceGhostEntity` | Place a ghost (construction plan) for an entity at map coordinates. |\n| `PlaceBlueprintString` | Import and build a blueprint string at a position. |\n| `GetGhostEntities` | Scan for ghost entities in an area. |\n| `CreateBlueprintFromArea` | Capture an area as an exportable blueprint string. |\n| `RevokeGhostEntity` | Remove a ghost entity at a position. |\n\n### Advanced\n\n| Tool | Description |\n|------|-------------|\n| `ExecuteLua` | Execute arbitrary Lua code via RCON. Use for advanced operations not covered by other tools. |\n\n## Project Structure\n\n```\nFactorioMCP/\n├── Program.cs                          # Host setup, DI, MCP server wiring\n├── Rcon/\n│   ├── RconClient.cs                   # Source RCON protocol over TCP\n│   └── RconPacket.cs                   # RCON packet types and record\n├── Models/\n│   ├── Goal.cs                         # Goal/step data model\n│   └── TrackedBuilding.cs              # Building memory data model\n├── Services/\n│   ├── FactorioService.cs              # High-level game operations via Lua\n│   ├── EnergyService.cs                # Electric network inspection via Lua\n│   ├── BlueprintService.cs             # Blueprint and ghost entity operations\n│   ├── GoalPlannerService.cs           # Goal tracking with JSON persistence\n│   ├── BuildingMemoryService.cs        # Building tracking with JSON persistence\n│   ├── GameCommandQueue.cs             # Serializes concurrent MCP tool calls\n│   └── RconConnectionService.cs        # RCON connection on startup\n├── Tools/\n│   ├── MovementTools.cs                # Walk, stop, get position\n│   ├── InventoryTools.cs               # Inventory, crafting\n│   ├── EntityTools.cs                  # Place/mine entities\n│   ├── InteractionTools.cs             # Insert/remove items, inspect entities\n│   ├── WorldTools.cs                   # Nearby entities, distance, scan\n│   ├── WaitTools.cs                    # Wait for crafting, position, ticks\n│   ├── ChatTools.cs                    # Chat message listener, send/receive\n│   ├── GoalTools.cs                    # Goal planning and tracking\n│   ├── EnergyTools.cs                  # Electric network and power inspection\n│   ├── ResearchTools.cs                # Research status, start research\n│   ├── RecipeTools.cs                  # Recipe and technology queries\n│   ├── BuildingTools.cs                # Building memory queries\n│   ├── BlueprintTools.cs               # Blueprint and ghost entity tools\n│   └── LuaTools.cs                     # Raw Lua execution\n└── Resources/\n    └── GameStateResources.cs           # MCP Resources (read-only game state)\n\nFactorioMCP.Tests/                      # Unit tests (xUnit)\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for workflow guidelines, CPX complexity scale, and coding conventions.\n\n## License\n\nSee repository for license details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbarisic%2Ffactoriomcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsbarisic%2Ffactoriomcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbarisic%2Ffactoriomcp/lists"}