Factorio Ai Companion

🚀 Factorio AI Companion

A bidirectional chat bridge between Factorio and Claude Code via the MCP protocol, enabling seamless communication between the game and the AI.

🚀 Quick Start

✨ Features

• Establishes a bidirectional chat between Factorio and Claude Code using the RCON protocol.
• Provides a set of tools for message retrieval and sending in the chat.
• Integrates with Factorio through a Lua mod and a Node.js MCP server.

📦 Installation

1. Install Dependencies

bun install

2. Install Factorio Mod

Windows:

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):

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

Or use the hidden settings GUI:

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

💻 Usage Examples

1. Start Factorio Multiplayer

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

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

2. Test RCON Connection (Optional)

bun run src/rcon/test-connection.ts

Expected output:

✅ RCON connected on attempt 1
✅ Connection successful!
✅ RCON is working!

3. Start MCP Server

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

4. Connect Claude Code

The .mcp.json file in the project root configures Claude Code to use this server. Claude Code will automatically start the MCP server when needed.

5. Test It!

In Factorio chat:

/companion Hello Claude! Can you help me?

In Claude Code:

Use the get_companion_messages tool

Claude will see:

[
  {
    "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!

📚 Documentation

Tools Available

get_companion_messages

Retrieve unread messages from the Factorio chat that start with /companion.

Returns: An array of {player, message, tick} objects.

send_companion_message

Send a message to the Factorio chat as an AI Companion.

Input: { message: string }

🔧 Technical Details

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"

• Ensure Factorio is running.
• Check that "Start as server" is enabled.
• Verify that the RCON port is 27000.
• Confirm that the RCON password is "factorio".

"No messages"

• Type /companion <message> in the Factorio chat (not just "companion").
• Check that the mod is enabled in the Factorio → Mods menu.
• Restart Factorio after installing the mod.

"Command not found"

• Make sure Bun is installed: https://bun.sh
• Run bun --version to verify.

Development

# Run tests
bun test

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

# Start MCP server
bun run src/index.ts

📄 License

This project is inspired by Factorio Learning Environment patterns and best practices.