# Factorio Ai Companion

> AI companions for Factorio 2.x via MCP. 51 RCON commands, hybrid mining, autonomous skills. Control companions with natural language through Claude Code.

- **Type:** MCP server
- **Install:** `agentstack add mcp-lveillard-factorio-ai-companion`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lveillard](https://agentstack.voostack.com/s/lveillard)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [lveillard](https://github.com/lveillard)
- **Source:** https://github.com/lveillard/factorio-ai-companion

## Install

```sh
agentstack add mcp-lveillard-factorio-ai-companion
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Factorio AI Companion

Bidirectional chat bridge between Factorio and Claude Code via MCP protocol.

## Status: ✅ Phase 1 Complete - Chat Bridge Working!

Bidirectional chat working between Factorio and Claude Code via RCON.

## Quick Start Guide

### 1. Install Dependencies

```bash
bun install
```

### 2. Install Factorio Mod

**Windows:**
```bash
xcopy /E /I factorio-mod "%APPDATA%\Factorio\mods\ai-companion"
```

**Linux/Mac:** See `factorio-mod/README.md`

### 3. Configure RCON in Factorio

Edit `%APPDATA%\Factorio\config\config.ini` and add these lines (if not already present):

```ini
local-rcon-socket=127.0.0.1:34198
local-rcon-password=factorio
```

**Or use the hidden settings GUI:**
1. In Factorio main menu, press **Ctrl+Alt** and click **Settings**
2. Go to **"The rest"** tab
3. Set `local-rcon-socket` to `127.0.0.1:34198`
4. Set `local-rcon-password` to `factorio`

### 4. Start Factorio Multiplayer

**Important:** RCON only works in multiplayer mode (even if playing solo).

1. Launch Factorio
2. **Multiplayer** → **Host New Game** (or **Load Game**)
3. Select your save and click **Play**
4. RCON will be automatically enabled

### 5. Test RCON Connection (Optional)

```bash
bun run src/rcon/test-connection.ts
```

Expected output:
```
✅ RCON connected on attempt 1
✅ Connection successful!
✅ RCON is working!
```

### 6. Start MCP Server

```bash
bun run src/index.ts
```

Expected output:
```
🚀 Starting Factorio MCP Server...
✅ RCON connected on attempt 1
📡 RCON connected to Factorio
✅ MCP server running on stdio

💡 Server is ready! Claude Code can now use:
   - get_companion_messages
   - send_companion_message
```

### 7. Connect Claude Code

The `.mcp.json` file in this project root configures Claude Code to use this server.

Claude Code will automatically start the MCP server when needed.

### 8. Test It!

**In Factorio chat:**
```
/companion Hello Claude! Can you help me?
```

**In Claude Code:**
```
Use the get_companion_messages tool
```

Claude will see:
```json
[
  {
    "player": "YourName",
    "message": "Hello Claude! Can you help me?",
    "tick": 12345
  }
]
```

**Claude can respond:**
```
Use send_companion_message with "Hello! I'm here to help!"
```

**In Factorio, you'll see:**
```
[AI Companion] Hello! I'm here to help!
```

## Tools Available

### `get_companion_messages`
Get unread messages from Factorio chat starting with `/companion`.

**Returns:** Array of `{player, message, tick}`

### `send_companion_message`
Send a message to Factorio chat as AI Companion.

**Input:** `{ message: string }`

## Architecture

```
Factorio (Lua mod captures /companion chat)
    ↕ RCON (TCP port 27000)
Node.js MCP Server (Bun)
    ↕ MCP Protocol (stdio)
Claude Code (You!)
```

## What's Built

- ✅ RCON client with retry logic
- ✅ Chat message parser
- ✅ Factorio Lua mod with FLE patterns
- ✅ MCP server with 2 tools
- ✅ Claude Code integration via .mcp.json

## Phase 2 (Future)

- AI-controlled character
- Game state introspection
- Automated building/crafting
- Multi-agent coordination

## Troubleshooting

**"Connection failed"**
- Make sure Factorio is running
- Check "Start as server" is enabled
- Verify RCON port is 27000
- Verify RCON password is "factorio"

**"No messages"**
- Type `/companion ` in Factorio chat (not just "companion")
- Check mod is enabled in Factorio → Mods menu
- Restart Factorio after installing mod

**"Command not found"**
- Make sure Bun is installed: https://bun.sh
- Run `bun --version` to verify

## Development

```bash
# Run tests
bun test

# Test RCON connection
bun run src/rcon/test-connection.ts

# Start MCP server
bun run src/index.ts
```

## Credits

Inspired by [Factorio Learning Environment](https://github.com/JackHopkins/factorio-learning-environment) patterns and best practices.

## Source & license

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

- **Author:** [lveillard](https://github.com/lveillard)
- **Source:** [lveillard/factorio-ai-companion](https://github.com/lveillard/factorio-ai-companion)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-lveillard-factorio-ai-companion
- Seller: https://agentstack.voostack.com/s/lveillard
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.