Content
# Factorio MCP Server
This is a Model Context Protocol (MCP) server for querying the status of a Factorio game server. This server communicates with the Factorio server using the `factorio-rcon` command to retrieve information such as server status, player list, and in-game time.
## Features
This MCP server provides the following tools:
- `get_server_status`: Retrieve the status of the Factorio server
- `list_players`: Get a list of currently connected players
- `get_game_time`: Retrieve the current in-game time
- `execute_command`: Execute any Factorio command
## Prerequisites
- Node.js version 18 or higher
- TypeScript
- The `factorio-rcon` command must be installed
## Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/factorio-mcp.git
cd factorio-mcp
# Install dependencies
npm install
# Build
npm run build
```
## Configuration
You can specify the connection information to the Factorio server by setting the following environment variables:
- `FACTORIO_SERVER_IP`: The address of the Factorio server (default: 127.0.0.1)
- `FACTORIO_RCON_PORT`: The RCON port (default: 27015)
- `FACTORIO_RCON_PASSWORD`: The RCON password
## Implementation Details
This MCP server is implemented using the latest MCP SDK (v1.8.0). The main implementation points are as follows:
1. Create the MCP server using the `McpServer` class
2. Each tool is defined using the `server.tool()` method
3. The `factorio-rcon` command is executed using `child_process.exec`
4. Error handling is implemented for each tool, returning appropriate error messages in case of failure
## MCP Server Configuration
Add the following configuration to Claude's configuration file:
### For Cline (VSCode extension)
Add the following to the `cline_mcp_settings.json` file:
```json
{
"mcpServers": {
"factorio": {
"command": "node",
"args": ["path/to/factorio-mcp/build/index.js"],
"env": {
"FACTORIO_SERVER_IP": "your server IP",
"FACTORIO_RCON_PORT": "27015",
"FACTORIO_RCON_PASSWORD": "your password"
},
"disabled": false,
"autoApprove": []
}
}
}
```
### For Claude Desktop App
Add the following to the `claude_desktop_config.json` file:
```json
{
"mcpServers": {
"factorio": {
"command": "node",
"args": ["path/to/factorio-mcp/build/index.js"],
"env": {
"FACTORIO_SERVER_IP": "your server IP",
"FACTORIO_RCON_PORT": "27015",
"FACTORIO_RCON_PASSWORD": "your password"
},
"disabled": false,
"autoApprove": []
}
}
}
```
## Starting the Server
To start the MCP server directly, use the following commands:
```bash
# Run after building
npm run start
# Or
node build/index.js
# Development mode (build and run simultaneously)
npm run dev
```
## Running on WSL and Connecting from Cline
To run the MCP server on WSL and connect from Cline (VSCode extension) on Windows, follow these steps:
1. Build and run the MCP server on WSL:
```bash
cd /path/to/factorio-mcp
npm install
npm run build
npm run start
```
2. Edit the Cline configuration file, usually located at:
```
C:\Users\jessiqa\AppData\Roaming\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
```
3. Add an entry like the following to the configuration file:
```json
{
"mcpServers": {
"factorio": {
"command": "wsl",
"args": ["-e", "node", "/path/to/factorio-mcp/build/index.js"],
"env": {
"FACTORIO_SERVER_IP": "your server IP",
"FACTORIO_RCON_PORT": "27015",
"FACTORIO_RCON_PASSWORD": "your password"
},
"disabled": false,
"autoApprove": []
}
}
}
```
4. Replace `/path/to/factorio-mcp/` with the actual path in WSL.
5. Restart VSCode or reload the Cline extension to apply the settings.
## Usage
After setting up the MCP server, you can use commands like the following in Claude:
```
Tell me the server status
```
Alternatively, you can directly invoke specific tools:
```
Show the player list of the Factorio server
```
## Troubleshooting
### RCON Command Configuration
This project uses the `rcon` command to communicate with the Factorio server. To ensure it works correctly, the following configuration is required:
1. **Create the rcon.yaml file**
```bash
mkdir -p ~/.config/rcon
cat > ~/.config/rcon/rcon.yaml << EOF
default:
address: 127.0.0.1:27015
password: your password
EOF
```
Note: The format of the YAML is important. Pay special attention to indentation.
2. **Check the permissions of the configuration file**
```bash
chmod 600 ~/.config/rcon/rcon.yaml
```
### Setting Environment Variables on WSL
When running the MCP server on WSL, be cautious about how you set environment variables:
1. **Temporary settings (valid only for the session)**
```bash
export FACTORIO_SERVER_IP="127.0.0.1"
export FACTORIO_RCON_PORT="27015"
export FACTORIO_RCON_PASSWORD="your password"
```
2. **Persistent settings (add to .profile)**
```bash
echo 'export FACTORIO_RCON_PASSWORD="your password"' >> ~/.profile
source ~/.profile
```
3. **Notes for non-interactive shells**
- Adding settings to `.bashrc` may not be read in non-interactive shells
- Instead, add settings to `.profile` or `.bash_profile`
### Testing and Verifying Connection
If you encounter connection issues, you can verify with the following steps:
1. **Check environment variables**
```bash
echo $FACTORIO_RCON_PASSWORD
env | grep FACTORIO
```
2. **Directly execute a command to test**
```bash
rcon -c ~/.config/rcon/rcon.yaml "serverinfo"
```
3. **Check the contents of the configuration file**
```bash
cat ~/.config/rcon/rcon.yaml
```
### Common Errors and Solutions
1. **"rcon.yaml: no such file or directory" error**
- The configuration file does not exist or the path is incorrect
- Create the `~/.config/rcon/rcon.yaml` file
2. **"cannot unmarshal !!str into config.Session" error**
- The format of the configuration file is incorrect
- Recreate the configuration file using the correct format above
3. **"authentication failed" error**
- The password is incorrect or not set
- Ensure the password in the configuration file matches the Factorio server password
4. **"factorio-rcon: command not found" error**
- This project has been updated to use the `rcon` command
- Ensure the `rcon` command is installed
### Issue with No Response Displayed
The Factorio server executes commands and displays messages in-game, but may not return responses through the RCON protocol. This is a limitation of Factorio and not an issue with the MCP server.
To check if the command was executed successfully, verify the in-game messages.
## License
MIT
