# factorio-mcp

MCP server for controlling and inspecting a Factorio 2.0 server over RCON.

It exposes tools for common server administration and game-state queries, plus escape hatches for raw console commands and Lua snippets.

## Requirements

- Node.js 23+ with native TypeScript stripping support
- A running Factorio server with RCON enabled
- An MCP client that can launch stdio servers

## Factorio RCON Setup

For a local Factorio game, enable RCON from the hidden advanced options:

1. Hold `Ctrl` + `Alt` while clicking **Settings**.
2. Click the newly visible **The rest** button.
3. Enable the local RCON socket.
4. Set an RCON password.
5. Use the same password as `FACTORIO_RCON_PASSWORD` when starting this MCP server.

For a dedicated server, start Factorio with RCON enabled, or set the equivalent values in your server config:

```bash
factorio --start-server save.zip \
  --rcon-port 27015 \
  --rcon-password "change-me"
```

Keep the RCON port private. This server can execute admin commands and arbitrary Lua through Factorio's `/silent-command`.

## Install

```bash
npm install
npm run typecheck
```

## Run

```bash
FACTORIO_RCON_HOST=localhost \
FACTORIO_RCON_PORT=27015 \
FACTORIO_RCON_PASSWORD=change-me \
npm start
```

Environment variables:

| Name | Default | Description |
| --- | --- | --- |
| `FACTORIO_RCON_HOST` | `localhost` | Factorio RCON host |
| `FACTORIO_RCON_PORT` | `27015` | Factorio RCON port |
| `FACTORIO_RCON_PASSWORD` | empty | Factorio RCON password |

## MCP Client Config

Example stdio configuration:

```json
{
  "mcpServers": {
    "factorio": {
      "command": "node",
      "args": ["/path/to/factorio-mcp/src/index.ts"],
      "env": {
        "FACTORIO_RCON_HOST": "localhost",
        "FACTORIO_RCON_PORT": "27015",
        "FACTORIO_RCON_PASSWORD": "change-me"
      }
    }
  }
}
```

If you install it as a package or link it locally, you can use the `factorio-mcp` bin instead of calling `node src/index.ts` directly.

## Tools

Command tools:

- `rcon_command`: execute a raw Factorio console command.
- `lua_exec`: execute Lua through `/silent-command`; return values are printed and tables are serialized with `serpent.line`.
- `send_chat`: send a chat message as `[MCP]`.
- `save_game`: save the current game, optionally with a save name.

Player tools:

- `get_players`: list connected players.
- `get_player_info`: inspect a player's position, inventory, health, and crafting state.
- `player_action`: kick, ban, unban, mute, unmute, promote, or demote a player.

Game-state tools:

- `get_game_status`: tick, age, player count, evolution, research, and speed.
- `get_research_status`: current research, progress, queue, and completed technologies.
- `get_production_stats`: item or fluid production and consumption stats.
- `get_surface_info`: surface details, pollution, and entity counts.
- `find_entities`: search entities by name, type, area, or radius.
- `get_logistics_info`: logistic network robot and storage information.
- `get_planets`: list Space Age planets.
- `get_space_platforms`: list Space Age platforms.
- `get_alerts`: active alerts for a force.
- `get_electric_network`: electric network production, consumption, and satisfaction.
- `get_train_info`: train state, schedules, and cargo.
- `get_player_surroundings`: nearby entities, resources, enemies, GUI state, cursor stack, vehicle, and walking state.

## Resources

- `factorio://server-status`: connection status and basic game information.

## Development

```bash
npm run typecheck
```

There is no build step at the moment; the server runs directly from `src/index.ts`.