sdv-mcp

This is a read-only MCP server that reads a Stardew Valley save and answers questions about it, and is pulls your most recent save data per-call. I recently got into the game with my wife and noticed I was spending more time reading the Stardew Wiki rather than playing, so I made this to answer the questions I had. It includes 54 tools, and also allows Stardew Wiki search through MediaWiki API. I made this with mainly vanilla in mind, so YMMV with mods.

[!CAUTION] This MCP is read-only and should not cause any issues, but safety first is always the best approach! Use a save copy first, not an original. Then once you feel comfortable, you can point it at your real save to receive the save-per-night updates.

Example questions that utilize the state of your save, tailoring responses to you depending on the season, day, location, and what you already have:

"What is my best money maker that I should be utilizing?"

"What should I focus on next?"

"Can anything be completed with what I have?"

"Best way to get coal?"

"Give me a priority step-by-step list on completing my fishing bundle."

"Where is the chest that has the pearl I need to gift to Clint?"

"How many sprinklers will I need to water all my Cauliflower seeds I have?"

Requirements

• Python 3.10 or newer.

• A Stardew Valley save file. The game stores saves at:

  • Windows: %APPDATA%\StardewValley\Saves\<FarmName>_<id>\<FarmName>_<id>
  • macOS/Linux: ~/.config/StardewValley/Saves/<FarmName>_<id>/<FarmName>_<id>

  Point the server at that save file or its folder (--save / --save-dir, or the SDV_SAVE_PATH / SDV_SAVE_DIR env var). The server never searches for saves on its own.

• One Python dependency — the mcp SDK (mcp>=1.2.0). Everything else uses the Python standard library (the wiki client is stdlib urllib), so there is nothing else to install.

• uv — only needed for the recommended uvx install method below (it provides the uvx command). Install it from docs.astral.sh/uv. Not required if you instead pip install the package or run from this folder.

Install it with either:

• uvx sdv-mcp (recommended — runs the published package directly, no manual install; requires uv), or
• pip install sdv-mcp (the published package), or
• pip install -r requirements.txt then python sdv_mcp_server.py (to run from this folder).

Keep the four modules in the same folder — the server imports the others from its own dir.

Install into a client

Recommended: uvx

Needs uv, pass a save folder/directory with --save-dir or just --save with the actual save file, which is just the same name as the folder/directory:

--save-dir example on Windows with Claude Desktop and proper JSON escapes:

{
  "mcpServers": {
    "sdv-mcp": {
      "command": "uvx",
      "args": [
        "sdv-mcp", // use "sdv-mcp@latest" to always pull the latest version
        "--save-dir", "C:\\Users\\you\\AppData\\Roaming\\StardewValley\\Saves\\FarmName_437005740"
      ]
    }
  }
}

uvx pulls the package from PyPI. Pin a version with sdv-mcp==0.1.0, or install the latest dev build straight from git by adding "--from", "git+https://github.com/vehemont/sdv-mcp" before "sdv-mcp".

Alternative: run a local checkout

{
  "mcpServers": {
    "sdv-mcp": {
      "command": "python",
      "args": [
        "/path/to/sdv-mcp/sdv_mcp_server.py",
        "--save-dir", "C:/Users/you/AppData/Roaming/StardewValley/Saves/FarmName_123456"
      ]
    }
  }
}

macOS/Linux use python3; pip install -r requirements.txt first.

Runs on stdio. You must point --save/--save-dir (or the env var) at the save you want; the server reads only that save and never scans your machine for others.

Disabling tools

By default, all tools are enabled. Any tool you consider cheating/unfair can be turned off so the model never sees it. Two knobs, both settable as a CLI arg (wins) or an env var:

• Denylist — --disable-tools a,b,c or SDV_DISABLE_TOOLS=a,b,c. Serves everything except those.
• Allowlist — --enable-tools a,b,c or SDV_ENABLE_TOOLS=a,b,c. Serves only those (disable is applied after).

{
  "mcpServers": {
    "sdv-mcp": {
      "command": "python",
      "args": [
        "/path/to/sdv-mcp/sdv_mcp_server.py",
        "--save-dir", "C:/Users/you/AppData/Roaming/StardewValley/Saves/FarmName_123456",
        "--disable-tools", "find_item,missing_museum,perfection"
      ]
    }
  }
}

Tools (46)

Save state

Inventory + location

Planning + completion

Calculators (save + verified game formulas)

Wiki verification

Files

• sdv_parser.py — the read-only save parser (ElementTree)
• sdv_wiki.py — MediaWiki Action API client (api.php; the wiki's rest.php returns empty, so Action API it is), cached + rate-limited
• sdv_calc.py — the calculators + reference tables
• sdv_mcp_server.py — the 54 tools

Known limits

• Vanilla + whatever the wiki documents only. Modded content lives on separate wikis.
• missing_recipes lists recipes you've learned but not made; recipes not yet learned show only as a count (they aren't in the save). shipping_tracker lists what you've shipped by name — a by-name "still to ship" list isn't modelled (the save only stores what shipped), so its remaining count is approximate vs the 154-item set.
• quests: completable_now covers item delivery/harvest/resource quests (you still hand the item in); monster/fishing/socialize quests report progress counters instead. Special-order objectives resolve their item (e.g. "Juice") and show due/days_left.
• Item names come from a bundled catalog (sdv_items.py) generated from the game's unpacked assets, plus a fallback that resolves anything present in your save. Regenerate for a new game version with python scripts/gen_items.py.
• Wiki tools need outbound network. The save tools don't.