Skip to main content
Glama

factorio-player-mcp

An MCP control layer for one dedicated, connected Factorio player.

The project measures gameplay through a constrained interface; it is not a general RCON or Lua automation server. The agent-facing API will expose only typed, legal player actions and bounded local observations. It will not expose arbitrary Lua/RCON, teleportation, item spawning, direct entity mutation, forced research, evaluator state, or full-map dumps.

Current status

The version 1 contract is defined. The repository contains an initial Factorio mod and stdio MCP bootstrap for bounded actor observation and native crafting. It is not benchmark-valid yet.

Related MCP server: Renge Bot

Development checks

The contract checks use only the Python standard library:

python3 -m unittest discover -s tests -v

These tests guard the public allow-list, forbidden capabilities, dedicated player identity policy, bounded observations, action-result fields, and versioned response schemas.

Host MCP bootstrap

The current stdio MCP server exposes only observe_actor, observe_local, craft, wait, move, mine, place, rotate, and interact_inventory. requires the Factorio mod to be installed and the game to be running with RCON enabled. The RCON password belongs only in the host-side MCP process; do not provide it to an agent.

uv sync
FACTORIO_RCON_HOST=127.0.0.1 \
FACTORIO_RCON_PORT=25575 \
FACTORIO_RCON_PASSWORD=replace-me \
uv run factorio-player-mcp

See mcp.json.example for a client configuration template.

Available Tools

6 tools
craftC

Queue an available recipe through the dedicated player's native craft queue.

ParametersJSON Schema
NameRequiredDescriptionDefault
countNo
recipeYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It hints that crafting is queued through a native queue and requires an available recipe, but does not describe permissions, resource consumption, queue limits, failure behavior, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no wasted words. It is concise, though quite sparse for a tool with undocumented parameters and no annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained. However, with no annotations and 0% schema description coverage, the description omits essential input details and usage context, leaving the definition noticeably incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain the two parameters. It does not describe the recipe string format or what the optional count parameter does, leaving parameter semantics entirely undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb (Queue) and resource (recipe) and references the player's native craft queue, making the action clear. It does not explicitly differentiate from sibling tools, but its purpose is distinct from observe, move, wait, and mine.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, prerequisites, or conditions for crafting. Usage is only implied by the tool name and description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mineC

Mine a reachable target through the dedicated player's normal mining state.

ParametersJSON Schema
NameRequiredDescriptionDefault
xYes
yYes
countNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full behavioral burden. It implies a game-state mutation (the player performs mining) but does not disclose what happens on failure, whether the player must be positioned first, whether the target is consumed, or any cooldown/range constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the verb first. It is not bloated, but "through the dedicated player's normal mining state" is low-value phrasing that could be trimmed without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return format need not be described, but with no annotations, 0% parameter coverage, and only one thin sentence, the definition is substantially incomplete for a 3-parameter action tool. It omits range prerequisites, failure behavior, and what count actually does.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 3 parameters, and the description adds nothing about x, y, or count. It never explains that x/y are target coordinates or what count controls (e.g., blocks to mine), leaving all parameter meaning to the bare schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ("Mine") and a resource ("a reachable target"), and it is clearly distinguishable from siblings such as craft, wait, move, and observe_*. However, "reachable target" is left undefined and "dedicated player's normal mining state" is vague jargon, so the action is not fully pinned down.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to call this instead of alternatives like move or craft, nor any stated prerequisites beyond the hint that the target must be reachable. The agent must infer that the target coordinates must already be in range before mining.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

moveC

Walk the dedicated player toward a target using normal movement state.

ParametersJSON Schema
NameRequiredDescriptionDefault
xYes
yYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it discloses almost nothing: it does not say whether the call blocks until arrival, what happens on unreachable targets, whether collisions or enemies interrupt movement, or what 'normal movement state' excludes (e.g., sprinting). The reference to a 'normal movement state' hints other states exist but is left unexplained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with no filler, front-loaded with the action. It is efficient, though its brevity is partly under-specification rather than disciplined concision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be described, but for a movement action with zero annotation coverage and zero parameter documentation, the description leaves critical behavioral questions (blocking vs. non-blocking, coordinate semantics, failure modes) unanswered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters (x, y) have 0% schema description coverage, so the description must compensate. It only obliquely implies the parameters are a target position ('toward a target'); it never states coordinate units, frame of reference, or whether the destination must be reachable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a recognizable action ('walk toward a target'), but the phrasing is vague: 'dedicated player' and 'normal movement state' are unexplained jargon, and nothing distinguishes it from siblings like mine or craft beyond the generic idea of moving. An agent can guess it moves the character, but the scope and specificity are thin.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no indication of when to use this versus wait, mine, or the observe_* tools, nor any prerequisites or conditions. The only implicit usage cue is 'toward a target,' which is not a when-to-use rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

observe_actorC

Return bounded state for the configured dedicated player.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. 'Bounded state' hints at a capped payload but never says what the cap is, what happens if no dedicated player is configured, whether this is a read-only polling call, or any rate/cost characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler, which is appropriate for a zero-parameter tool. It is not padded, though it is arguably too terse to front-load anything beyond the verb and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and there are no parameters to cover. That said, with zero annotations the description leaves key behavioral questions (bounded how, unavailable-actor behavior, read-only nature) unanswered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so the schema offers nothing to document; baseline is 4. The phrase 'configured dedicated player' does add the useful notion that the target is set elsewhere rather than passed in, which is meaningful given the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a verb ('Return') and a resource ('state for the configured dedicated player'), which loosely separates it from observe_local. But 'bounded state' is undefined jargon — an agent cannot tell what state fields (position, health, inventory, surroundings) are returned, so the purpose stays vague rather than specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no when-not-to-use, and no mention of the sibling observe_local despite the near-identical name. The reader must infer the local-vs-remote distinction themselves.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

observe_localC

Return chart-bounded entities within a small radius of the dedicated player.

ParametersJSON Schema
NameRequiredDescriptionDefault
radiusNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the behavioral load. It says it returns entities but omits permissions, side effects, rate limits, and explicit read-only status; 'Return' implies a read but is not a full disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler, which is appropriate for a simple read tool. The only weakness is that the compact phrasing relies on jargon that could have been clarified without adding much length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be explained, but the description still lacks usage context and an explanation of the radius parameter. Given no annotations and 0% parameter coverage, it is not complete enough for reliable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for the single radius parameter, and the description only says 'small radius' without defining units, default value (10), or how changing it affects results. It therefore does not compensate for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Return') and resource ('entities') and scopes it to a small radius around the dedicated player, so the operation is understandable. It does not, however, distinguish this from the sibling observe_actor, leaving route selection to the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use observe_local instead of observe_actor, move, mine, or the other siblings. The 'small radius' phrase hints at local scouting, but no conditions, exclusions, or alternatives are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

waitC

Wait for a bounded number of normal Factorio game ticks.

ParametersJSON Schema
NameRequiredDescriptionDefault
ticksYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It usefully clarifies that the unit is game ticks rather than wall-clock time and that the wait is 'bounded', but it never says what the bound is, what happens if the bound is exceeded, whether the call blocks, or whether the game state advances during the wait. 'Bounded' is asserted without the boundary being defined.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with the key constraint front-loaded and no wasted words. The only minor cost is that 'bounded' hints at a limit the description never supplies, leaving the reader with an unresolved detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter, non-destructive wait tool with an output schema (so return values need not be explained), the description covers the essential semantics of the call. However, with no annotations and 0% schema coverage, the undefined bound and the absence of any when-to-use guidance leave it only minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema documents nothing about the single required integer 'ticks'. The description does add the crucial unit ('normal Factorio game ticks') and treats the value as a count, but it omits the valid range, any maximum, and what happens if the bound is violated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Wait') on a specific resource ('normal Factorio game ticks'), which is enough to distinguish it from the sibling action tools (craft, move, mine). It is clear what the tool does, though it never contrasts itself explicitly with observe_local or observe_actor, which are the closest alternatives for advancing/pausing interaction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus the observation siblings, nor any condition or prerequisite for waiting. The only implicit guidance is the unit of waiting being game ticks. An agent must infer the use case (let the simulation advance) entirely on its own.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv0.1.8
    • First observedcraft
    • First observedmine
    • First observedmove
    • First observedobserve_actor
    • First observedobserve_local
    • First observedwait

TDQS

B3/5.0

Scored across 6 tools

Disambiguation4/5

observe_actor and observe_local are the only pair with potential overlap, but their descriptions clearly distinguish full player state from nearby entities. The action tools (craft, wait, move, mine) each target a distinct operation.

Naming Consistency4/5

Two observation tools use a consistent verb_noun pattern (observe_actor, observe_local), while the remaining four are bare verbs (craft, wait, move, mine). This is a minor deviation from a single convention but remains readable and predictable.

Tool Count5/5

Six tools is a well-scoped minimum for basic player control: observe (global/local), act (move, mine, craft), and wait. Each tool earns its place without redundancy.

Completeness3/5

Core locomotion, mining, crafting, and observation are covered, but major Factorio player operations are absent: placing/removing buildings, inventory management, attacking, and interacting with entities. These gaps would block common agent workflows beyond simple resource gathering.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables controlling a semi-autonomous Minecraft bot via MCP, supporting tasks like movement, combat, farming, and chatting.
    -
  • F
    license
    Not graded
    quality
    C
    maintenance
    Enables controlling an autonomous Minecraft Java Edition player through MCP, with structured world perception, navigation, gathering, crafting, combat, building, skill-based task execution, and long-term memory integration.
    -