# 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 58 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,<2`). 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](https://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](https://docs.astral.sh/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:
```json
{
  "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](https://pypi.org/project/sdv-mcp/). 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
```json
{
  "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).

```json
{
  "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
| Tool | What |
|------|------|
| `save_status` | Save freshness: file path, last-modified time, age, in-game date. Every save-backed result also carries a `_save` stamp (in-game date + file mtime/size) so the model can tell if earlier data is stale — compare its `_save.mtime_ns` to a fresh `save_status()` (equal = current, different = re-run the tool) |
| `overview` | Date, players, shared money, lifetime earnings, deepest mine, version |
| `players` | Per-player levels, XP, XP-to-next, professions, spouse, backpack, house (`{'players': [...]}`) |
| `community_center` | Rooms done/left, incomplete bundles + exact items needed, Vault status |
| `museum` | Donations / 95 + next milestone with its actual reward (60 = Rusty Key) |
| `monster_goals` | Guild eradication goals: kills vs target + reward (`{'goals': [...]}`) |
| `friendships` | Villager hearts/points + spouse, per player |
| `gift_log` | Gifting planner: per-villager gifts today/this week (2/wk cap), status + full gift history (zero-count entries dropped) |
| `player_stats` | In-game Stats tab: all counters (steps, shipped, fish caught, geodes, quests...) + per-species monster kills |
| `player_tools` | Each player's tools + upgrade tier |
| `wallet` | Keys/special items (Rusty Key, Skull Key, Club Card, ...). 1.5 + 1.6 aware (reads mail flags) |
| `unlocks` | Which gated locations/vendors are reachable (Desert + Desert Trader, Sewers/Krobus, Skull Cavern, Casino, Quarry, Greenhouse, Minecarts, Movie Theater, Guild, Ginger Island) + how to unlock the rest |
| `feed` | Animals, silo hay, fiber, days of feed covered (+ fiber-as-grass-starters) |
| `full_report` | All of the above in one shot |

### Inventory + location
| Tool | What |
|------|------|
| `inventory` | Backpacks + chests. `full=True` = all items; `by_container=True` = per-chest |
| `processing` | Held crops grouped fruit/veg/special by the save's own item category |
| `machines` | Inventory of placed machines (Furnace, Keg, Cask, Seed Maker, Kiln, Tapper, ...) by type with counts + state (ready/working/idle) + a by-location breakdown |
| `buildings` | Farm buildings + per-player farmhouse upgrades: barn/coop tiers, animal capacity vs occupancy, silo/stable/mill/greenhouse/obelisks, cellar & kitchen unlock status |
| `chests` | Every container: type (Chest/Stone/Big/special), map + tile, color, contents |
| `find_item` | Where is X? Searches backpacks, chests, machine outputs. Map + tile + color |
| `net_worth` | Gold + sellable value of everything held (from each item's own price) |

### Planning + completion
| Tool | What |
|------|------|
| `quests` | Per-player quest journal + special-orders board (objectives + progress); item quests show requested item, on-hand count, and `completable_now`. `research=True` attaches a wiki `how_to_obtain` summary + infobox for each requested item |
| `can_complete_now` | CC bundles you could finish from what's in your chests right now |
| `bundle_sourcing` | Incomplete bundles + per missing-item wiki how-to-obtain + unlock-aware `locked_source_hints` (flags sources behind gated locations) |
| `missing_museum` | Undonated minerals + artifacts, with where they drop |
| `collections` | Collection tabs (multiplayer-aware, unioned across all farmers): fish caught (count + personal-record size), minerals/artifacts found — each checked against the SHARED farm museum (what the farm still needs). Fish are never donatable; only artifacts + minerals are |
| `cooking` | Cooking recipes known-but-not-made, with ingredients + on-hand count (cookable now). Kitchen access is farm-wide — anyone can cook if ANY house is upgraded (or they hold a Cookout Kit) |
| `missing_recipes` | Cooking/crafting recipes learned-but-not-made (+ how many not yet learned), per player |
| `shipping_tracker` | Items shipped by name + qty; distinct count vs the 154 Full-Shipment target |
| `golden_walnuts` | Ginger Island walnut progress: found vs 130, unspent, island-unlock + repeatable sources |
| `secret_notes` | Secret Notes found (1-25) with per-note found/missing flags |
| `tailoring` | Every item you've tailored at the sewing machine / Emily's (resolved to names) |
| `raccoon` | The 1.6 Raccoon storyline: requests completed, stage, times fed, current-request season |
| `perfection` | Real weighted Perfection %: 11 categories, each with have/total + earned %. 1.6-accurate (Farmer Level = player.Level/25) + per-player co-op breakdown |
| `daily_briefing` | Morning digest: luck, today/tomorrow weather, day-of-week + traveling cart (Fri/Sun), birthdays, festivals, open quests/special orders with `due`/`days_left`, machines/crops ready, pets due |
| `gift_helper` | Birthdays (from save) + your hearts + loved gifts, flags what you already hold |
| `ready_to_collect` | Machines with product ready (name, product, location + tile) + crops ready to harvest |
| `fish_available` | Fish catchable now (season/weather/time), `only_uncaught` filters |
| `mods` | Detect mods; list what couldn't map to vanilla (modded ids, unmapped bundle/museum) |

### Calculators (save + verified game formulas)
| Tool | What |
|------|------|
| `skill_xp_forecast` | Actions to hit a target skill level (farming XP formula) |
| `fishing_xp_forecast` | Catches to a target fishing level (difficulty/perfect/treasure/legendary) |
| `processing_planner` | Kegs/jars to clear the crop backlog in N days + est. gross gold |
| `processing_value` | Raw vs wine/juice vs jelly/pickle for a crop (Tiller/Artisan/quality aware) |
| `crop_planner` | Crops that mature in the window + profit/tile (`quality_weighted` optional) |
| `crop_quality_odds` | Gold/silver/normal/iridium % from farming level + fertilizer + food buff |
| `sprinkler_plan` | Sprinklers + materials for N tiles, and whether your bars can build them |
| `build_planner` | Total materials to craft a set of machines (e.g. '20 Keg, 5 Tapper'), with bars rolled down to ore + coal + furnace-time and resin/syrup to tapper-nights, vs your inventory |
| `fish_pond_forecast` | Days to fill a pond to capacity + roe notes |
| `friendship_forecast` | Loved gifts + weeks to a target heart level |
| `animal_product_quality` | Iridium/gold/silver produce odds per animal (friendship + mood + prof) |
| `animal_product_value` | Raw (Rancher) vs processed (Artisan) value of milk/egg/wool |
| `list_buffs` | Food buffs that raise a skill level (Farmer's Lunch +3, Trout Soup +1) |

### Wiki verification
| Tool | What |
|------|------|
| `wiki_search` | Search the Stardew Valley Wiki (titles + snippets) |
| `wiki_page` | A page (or one section) as clean text — to verify facts / pull context. Rough input (`puffer fish`, `sturgeon`) is auto-resolved to the right page |
| `wiki_infobox` | A page's infobox as structured fields (price/season/location). Auto-resolves rough input |
| `wiki_category` | Every page in a wiki category (e.g. `Spring fish`, `Summer crops`) — answer "all X in season Y" exhaustively. Case-insensitive (`Summer Crops` works) with near-match suggestions |
| `how_to_obtain` | Every way to get an item (drops, shops, trades, gifting) — the wiki lead summary + infobox source. Plan how to get a quest/bundle item. Auto-resolves rough input (`bat wing`, `large goat milk`) |
| `villager_schedule` | A villager's wiki schedule + your save's date/weather/hearts |

## 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 58 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`. `days_left` is omitted for untimed quests (billboard/fetch quests have no timer).
- 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.