Stardew Valley MCP Bridge

A hybrid AI-controlled game mod that bridges Stardew Valley with AI assistants via the Model Context Protocol (MCP). Enables autonomous AI agents to control and play Stardew Valley through real-time game state synchronization.

Architecture

┌─────────────────────────────────────────────────────────┐
│ STARDEW VALLEY (Game)                                   │
│   SMAPI Mod (C# .NET 6)                                 │
│     ModEntry → GameStateSerializer                      │
│              → CommandExecutor (w/ Pathfinder)          │
│              → WebSocketServer                          │
└─────────────────────────────────────────────────────────┘
              ↕ ws://localhost:8765/game
┌─────────────────────────────────────────────────────────┐
│ MCP Server (Go)                                         │
│   GameClient: WebSocket connection, state tracking      │
│   StardewAgent: 12 tools + 30 cheats, autonomous loop   │
└─────────────────────────────────────────────────────────┘
              ↕ Copilot SDK
┌─────────────────────────────────────────────────────────┐
│ Claude Sonnet (via GitHub Copilot SDK)                  │
└─────────────────────────────────────────────────────────┘

Prerequisites

For the SMAPI Mod

• Stardew Valley (game)
• SMAPI (Stardew Modding API) v4.0.0+
• .NET 6.0 SDK

For the MCP Server

• Go 1.23+
• GitHub Copilot access (for Claude Sonnet via Copilot SDK)

Building

1. Build the C# Mod

cd mod/StardewMCP
dotnet build

This compiles StardewMCP.dll and places it in bin/Debug/net6.0/.

2. Build the Go MCP Server

cd mcp-server
go build -o stardew-mcp

This produces the stardew-mcp executable.

Installation

Install the SMAPI Mod

1. Build the mod (see above)
2. Copy the entire mod/StardewMCP/bin/Debug/net6.0/ folder to your Stardew Valley mods directory:
   • Windows: %AppData%\StardewValley\Mods\StardewMCP\
   • macOS: ~/.config/StardewValley/Mods/StardewMCP/
   • Linux: ~/.config/StardewValley/Mods/StardewMCP/
3. Copy manifest.json to the same folder

Or use SMAPI’s mod folder structure:

Mods/
└── StardewMCP/
    ├── manifest.json
    ├── StardewMCP.dll
    └── (other build outputs)

Usage

1. Start Stardew Valley with SMAPI

Launch the game through SMAPI. The mod will automatically start a WebSocket server on ws://localhost:8765/game.

2. Load a Save File

The mod activates once you load into a game save.

3. Run the MCP Server

cd mcp-server
./stardew-mcp                    # Run with default autonomous mode
./stardew-mcp -auto=false        # Connect without starting AI agent
./stardew-mcp -goal "Clear the farm and plant parsnips"
./stardew-mcp -url ws://localhost:8765/game  # Custom WebSocket URL

The server connects to the game via WebSocket and begins the autonomous AI agent loop.

Available AI Tools

The AI agent has access to 12 tools for controlling the game:

Cheat Mode

Cheat mode provides instant god-mode capabilities for rapid testing or stress-free gameplay. Must call cheat_mode_enable first before any other cheat commands work.

Mode Control

Teleportation

Farming Automation

Pattern Drawing

Resources & Items

Social

Upgrades

Example: Instant Farm Setup

1. cheat_mode_enable
2. cheat_warp Farm
3. cheat_clear_debris, cheat_cut_trees, cheat_mine_rocks
4. cheat_hoe_all
5. cheat_plant_seeds (with seedId "472" for parsnips)
6. cheat_grow_crops
7. cheat_harvest_all

WebSocket Protocol

The mod and server communicate via JSON over WebSocket.

Request format:

{
  "id": "uuid",
  "type": "command",
  "action": "move_to",
  "params": {"x": 10, "y": 20}
}

Response format:

{
  "id": "uuid",
  "type": "response",
  "success": true,
  "message": "Moved to position",
  "data": {}
}

Configuration

• WebSocket Port: Default 8765 (configured in WebSocketServer.cs)
• Tool Cooldown: 30 game ticks between tool swings (~0.5s at 60fps)
• State Broadcast: Game state sent every 1 second
• Pathfinding: A* with 50,000 iteration limit, 30-tile scan radius

Troubleshooting

Mod not loading: Ensure SMAPI 4.0.0+ is installed and the mod files are in the correct Mods folder structure.

WebSocket connection failed: Check that the game is running and a save is loaded. The server retries connection every 5 seconds.

Pathfinding failures: The A* algorithm attempts up to 5 path recalculations. Some areas may be unreachable due to obstacles.